Kotharo v0.8.3
Docs menu

Troubleshooting

On this page

Run /kotharo:setup first when something seems off. It checks every tool, binding and setting it knows about, says what isn't ready, and changes nothing without your OK.

Python not found

The rules don't load, and Claude says:

Kotharo needs Python 3.11 or later and found none (tried python3, py -3, python). Install it from python.org, or set KOTHARO_PYTHON to its path.

Install Python 3.11 or later, or point KOTHARO_PYTHON at the one you have. If KOTHARO_PYTHON is set, Kotharo uses only that path and doesn't search, so check it points at a working Python.

Nothing loads on Windows

Kotharo's hooks and skills run in Git Bash. Without Git for Windows, Claude Code runs them in PowerShell and the Kotharo rules don't load. Install Git for Windows, then start a new session.

Managed settings

If your organization manages Claude Code settings, some of them switch parts of Kotharo off, often without a message. Ask your admin about these:

  • allowManagedHooksOnly: the band, the stop cards, the context ring, the guardrails, session continuity and the rules don't run, and /kotharo:team has no band to stop you in. The fix is to force-enable kotharo@kotharo in managed enabledPlugins.
  • allowManagedPermissionRulesOnly: the repo's committed permission rules and your "don't ask again" answers are ignored, so the same prompts come back on every ticket, and in auto mode the band shows no ticket status.
  • strictKnownMarketplaces: adding the marketplace fails until https://plugins.kotharo.com/marketplace.json is on the list.
  • allowedMcpServers or allowManagedMcpServersOnly: the servers your adapters use must be allowed.

Under managed settings, the session continuity hooks run only when the managed settings list kotharo@kotharo.

  • For Jira, the band needs your Jira site as a bare host, such as jira.example.com, with no https:// and no path. A value that isn't a host is treated as unset. Run /kotharo:setup to set it, or /kotharo:config set options.jira_site <host> --user.
  • The status comes from your tracker's MCP server, so that server must be connected and signed in. Check with /mcp.
  • In auto mode, Claude Code refuses the band's lookup unless a rule allows that one read-only tool. /kotharo:setup finds the tool and adds the rule with your OK.

A tool isn't connected or signed in

At the start of a session, Kotharo checks the repo's bindings and names any that may not run, such as:

Kotharo binding check: these slot bindings for this repo may not run.

Each line under it says what is missing, such as a command line tool to install, and what to run. A server you added in this session shows as connected only from a new session. Sign in with /mcp, start a new session, and run /kotharo:setup again.

When the ticketing tool is down rather than signed out, the team keeps working: it queues ticket changes and gives new tickets a local key such as LOCAL-1. Run /kotharo:sync-tickets once the tool is back, and it sends them after one OK.

A settings file is refused

Every settings file is checked against the core defaults. A bad one is refused with its error and changes nothing. The common errors:

  • <key>: not a key in the core defaults: a typo, or a key from another version. /kotharo:config show --origin lists the real ones.
  • <key>: expected <type>, got <type>: such as a string where a list belongs. A tool binding is a list, such as ["jira"].
  • <key> = <value> relaxes a safety default, so only --user or --repo can set it.: set it in your own file or the repo's committed one. See /kotharo:config.
  • A repo whose .claude/kotharo.toml and CLAUDE.md ### Toolchain bind the same slot to different tools: remove one, or make them agree.

When the autonomy settings are invalid, Kotharo applies its rules unchanged and Claude says so at the start of its first reply. Fix the file /kotharo:config names.

A marketplace named kotharo already exists

A machine can have only one marketplace named kotharo. Remove the one you have, then add the other and install again:

claude plugin marketplace remove kotharo

Auto-update can't be turned on

If setup says your settings have no extraKnownMarketplaces entry for kotharo, the marketplace was added some other way. Add it again with claude plugin marketplace add, or turn auto-update on from /plugin, under Marketplaces.

Too many permission prompts

Outside auto mode, Claude Code asks before every tool call no rule allows, including the team's own git and test commands. /kotharo:team says so in its estimate and first stop, with about how many prompts to expect and how many of setup's rules the repo lacks, and the band shows manual mode while the lane runs. A prompt from a background helper shows nowhere you look, so when a helper has run quietly for a while the band says the team may be waiting on a permission prompt: look for the prompt in that session. Run /kotharo:setup to add the missing rules. Answer "Yes, and don't ask again" for the safe ones, or add allow rules for your repo's build and test commands to its committed .claude/settings.json. Rules never need to cover pushes, merges, deploys or ticket changes: Kotharo asks for those itself. See Autonomy levels.

Next: Roles and tiers. All docs