Skip to content

Which setup command do I need?

mokata init, mokata setup claude, and installing the plugin are three different things, and the most common mokata support question comes from treating them as one. They answer three separate questions, and you may need one, two, or all three.

The decision table

You want… Run What it touches What it does NOT do
A governed config in this repo — profile, capability chains, the constitution, the audit ledger mokata init (interactive) .mokata/ in the current directory Does not touch Claude Code. No slash commands, no Agent Skills, no MCP server, no hooks. Your agent is unchanged. ⚠ mokata init --yes is the exception — see below.
mokata inside Claude Code — slash commands, Agent Skills, the MCP server, the gate hooks, the status line mokata setup claude .claude/ (commands, skills, settings.json) + the MCP registration. Runs init for you if .mokata/ is missing Does not install the mokata package (pip already did that), and does not replace pip install -U when a new version ships.
One-click install from Claude Code's plugin directory /plugin install mokata@mostack Claude Code's own plugin cache — a self-contained copy with its own hooks and MCP registration Does not put the mokata CLI on your PATH, and is not rewired by mokata setup claude. (Planned — mokata is not yet registered on a marketplace. Use the pip path today.)

The one-line version

  • init = your repo. It writes .mokata/.
  • setup = your agent. It writes .claude/.
  • plugin = an alternative to setup, not an alternative to init.

Do I need both init and setup?

Run mokata setup claude and you are done — it initializes the repo as part of wiring the harness. Run mokata init on its own only when you want mokata's engine from the terminal, from CI, or from a non-Claude agent, with your Claude Code setup left alone.

mokata init --mode seatbelt|memory|full picks how much of the engine to configure. It is a profile choice, not a wiring choice — no mode wires Claude Code.

🔴 --yes wires the harness (changed in 0.0.19)

The sentence above used to end "after any init, the harness is wired by mokata setup claude or not at all." That is no longer true, and the difference matters most to the people least likely to be watching a terminal.

mokata init --yes now runs setup claude at project scope as part of the init. --yes is consent to the whole plan, and wiring the run-state gate is part of that plan, so the consent is already given rather than assumed. Concretely, a non-interactive init writes:

  • .claude/commands/ (the slash commands) and .claude/skills/ (the Agent Skills);
  • .claude/settings.json — the SessionStart briefing, secret-guard, gate-guard, the MCP permission grant, and the status line (existing JSON is merged, never overwritten);
  • .mcp.json — the mokata MCP server registration;

and it spawns a short-lived mokata-mcp subprocess to check the server answers and serves the same version as the CLI. CI and scripted callers that timed or sandboxed mokata init should expect those writes and that subprocess. Reverse it with mokata unsetup claude --scope project.

This applies to --mode too: mokata init --mode memory --yes wires; mokata init --mode memory on a terminal does not.

An init that wires nothing is not silent either — it prints whether the run-state gate is enforcing here, in three states: enforcing, not wired, or could not be verified.

mokata init --preview previews the whole write. On its own it shows the .mokata/ plan and states that harness wiring is not part of that run, naming --yes, the wizard's offer and mokata setup claude. With --yes it also renders the harness plan — through the same renderer the wiring uses, so the preview cannot drift from what lands.

Upgrading mokata

Installing the new package is not the whole upgrade. pip install -U mokata replaces the code; it does not touch .claude/settings.json, which still carries the wiring the previous version wrote. A hook added — or a tool matcher widened — since your last mokata setup claude is simply not there. Nothing errors. The gate just never fires.

The one command

mokata upgrade

mokata upgrade finishes the job:

  1. it proposes pip install -U mokata and asks before running it;
  2. it then re-runs mokata setup claude, which previews the change and asks again before writing settings.json;
  3. it runs mokata doctor --wiring and reports.

Both writes are human-gated: decline either and nothing is written. mokata upgrade --yes approves both non-interactively (the plan is still printed), and --no-refresh skips the re-wiring if you want to do it yourself.

Restart Claude Code afterwards so it reloads settings.json.

Upgrading by hand

If you run pip yourself, run the other two steps yourself too:

pip install -U mokata
mokata setup claude          # refresh the harness wiring (previews, asks first)
mokata doctor --wiring       # confirm the gates resolve and the wiring is current

From a source checkout, the first step is git pull && pip install -e .; the last two are the same. On the plugin route, update through Claude Code (/plugin marketplace update mostack, then /plugin install mokata@mostack) and verify with mokata doctor --wiring — mokata setup claude is not the plugin's remedy.

How you find out the wiring went stale

You do not have to remember to check. The same verdict reaches you three ways:

  • the SessionStart briefing carries one line when — and only when — your wiring is out of date;
  • the status MCP tool reports it, which is what covers the case where the hooks are dead and therefore cannot tell you anything themselves;
  • mokata doctor --wiring answers on demand and exits non-zero when the wiring is not both launchable and current.

If the wiring is current, none of them say anything.