Getting started with mokata¶

No clone required. One instruction sets mokata up and the same one updates it — install or upgrade the isolated mokata CLI, then mokata setup claude. The Claude Code plugin is the alternative. Pick the path that matches how you work.

Path A — In Claude Code (recommended)¶

You get the full spec-driven TDD workflow (brainstorm → spec → develop → review → ship) as slash commands and Agent Skills inside Claude Code, plus the bundled MCP server.

A1 · Set up or update — the same instruction every time, in your repo:

uv tool install --upgrade mokata   # installs mokata, or upgrades it (or: pipx install --force mokata)
mokata setup claude                # wires the repo — runs `mokata init` too if the repo has no .mokata/
# restart Claude Code, then:
mokata doctor

mokata setup claude runs mokata init for you on a repo with no .mokata/; on a repo that has one it keeps your config, memory and ledger and refreshes only the wiring (new commands appear, stale ones are removed). Re-run it after every upgrade. You don't need mokata init separately unless you want mokata's config in a repo without wiring Claude Code (another AI tool, CI — Path B), and you never need init --force to update: it resets the repo's config to defaults. (macOS/Linux can also install with brew install JasGujral/mokata/mokata, then mokata setup claude.)

A2 · Alternative — the plugin, two commands inside Claude Code, nothing installed into your project. Use A1 or A2 in a repo, not both: both wire the same hooks.

/plugin marketplace add JasGujral/mokata-oss
/plugin install mokata@mostack

The plugin's commands are namespaced (/mokata:<name>). Its MCP server starts through uvx, so uv must be on your PATH. Details: Install the plugin.

Plain pip, last. pip install mokata (Python 3.10+) installs the same CLI — but inside a project venv this mixes mokata's deps into yours — prefer the above. mokata doctor warns when mokata is installed inside the repo's own environment. All routes: Install mokata.

Verify it worked:

mokata mcp status           # expect: mokata-mcp: REGISTERED ✓ … connected ✓

Then, inside Claude Code, start with /brainstorm (a new problem) or /refine (existing code). If the MCP tools ever stop showing up, just tell Claude "mokata mcp isn't working" and the /mcp-repair repair skill will re-register it (you'll need to restart Claude Code after).

Python version. mokata requires Python ≥ 3.10; the MCP server ships and runs out of the box on a plain pip install mokata.

Approving a write¶

mokata's writes are gated on you, not on the model. When the agent wants a durable write (memory, config, a session bundle) nothing is committed: it gets back a proposal id. You run mokata approve <id> in your own terminal, and the agent re-tries the same write, which then commits once. The approval is single-use, content-hashed (change an argument and the id no longer matches), and expires after 15 minutes. Bare mokata approve lists what's waiting.

By default there is no approve tool or slash command inside Claude Code — a model must never approve its own write. (An in-chat MCP approve tool ships but is opt-in, default-OFF, and even when enabled Claude Code prompts you on every call.)

The two guards on Claude's file writes¶

mokata setup claude also wires two blocking hooks (on by default; --no-hooks opts out):

secret-guard — a write carrying a secret is blocked outright. Never overridable, and it still blocks a write you did approve: approval is a methodology gate, never a security override.
gate-guard — inside an active run, an implementation write is blocked if there's no spec yet, no failing test on record, or the write strays outside the spec's authorized scope. Test files are always writable, and editing your repo outside a run is never policed. mokata gate status shows what's enforced here; mokata gate override <gate> --reason "…" lifts one gate for the session — explicit, re-confirmed, and on the audit ledger.

Pick how much you want on — `--mode`¶

You don't have to take everything at once. mokata init --mode is a graduated on-ramp: three named starting points, each of which configures the engine in this repo and prints the one command that proves it.

--mode chooses how much of the engine to configure — it is a profile choice, not a wiring choice. Interactively, no mode wires Claude Code; that is mokata setup claude (Path A above), which you only need once. ⚠ With --yes it is different: since 0.0.19 a non-interactive init (with or without --mode) does wire the harness — see the note under Path B. See Which setup command do I need?.

mokata init --mode seatbelt    # just the gates (and the code graph they need to be real)
mokata init --mode memory      # the gates + typed project memory that survives every session
mokata init --mode full        # everything the spine can wire

A mode is an alias for a profile plus an onboarding flavour, never a second thing to configure. It resolves to an existing profile, and the profile is the only thing persisted — a manifest written by --mode memory is byte-identical to one written by --profile standard. --mode and --profile are mutually exclusive; pass whichever you think in.

Mode	Profile it aliases	What you get
`seatbelt`	`standard`	The spec-driven TDD engine, the governance gates, and the built-in AST code graph the blast-radius gate needs to answer structurally instead of by grep.
`memory`	`standard`	Everything seatbelt gives you, plus typed project memory on the local SQLite store — rules, decisions and context that outlive the session.
`full`	`full`	The gates, persistent memory, and every graph and memory provider the spine knows about (each degrades to its floor when absent).

memory and full additionally offer the optional local embeddings model for semantic recall — an interactive, one-time ask you can decline; seatbelt structurally never offers it. No offer ever fires non-interactively, so --yes and CI runs can never reach pip.

Not sure? Plain mokata init (profile standard) is the same configuration as seatbelt.

Path B — Terminal CLI (any AI tool, CI, scripting)¶

You get the engine — gates, memory, structural queries, the audit ledger — driven from the terminal.

pipx install mokata         # or: uv tool install mokata · brew · plain pip last (see Path A)
mokata init                 # scaffold a governed config in THIS repo (.mokata/) — not Claude Code
mokata brainstorm           # or: mokata --help to see every command

Run interactively, mokata init writes .mokata/ and stops there: it does not add slash commands, Agent Skills, the MCP server, or the gate hooks to Claude Code. Path A's mokata setup claude is what does that (and runs init for you). Unsure which you need — or upgrading an existing install? See Which setup command do I need?.

🔴 mokata init --yes behaves differently, and this changed in 0.0.19. --yes is read as consent to the whole init plan, and wiring the run-state gate is now part of that plan — so a non-interactive init also runs setup claude at project scope. It writes .claude/commands/, .claude/skills/, .claude/settings.json (hooks, the MCP permission grant and the status line) and .mcp.json, and it spawns a short-lived mokata-mcp subprocess to verify the server answers. If you call mokata init --yes from a script or CI, expect those files and that subprocess. An init that wires nothing instead prints a line saying the gate is not enforcing, so either way you can tell.

--preview previews the whole write. On its own it shows the .mokata/ plan and says plainly that harness wiring is not part of that run; with --yes it also shows the harness plan the wiring itself renders — the commands, the Agent Skills, .mcp.json and .claude/settings.json.

Working as a team¶

Everything above is local mode — the zero-config default. When you're ready to share memory, sessions, and a governed audit trail across a team, one person runs mokata team init and everyone else reaches CONNECTED with a single guided mokata team join. See Team mode — setup & operations for the full path (and its security model).

Path C — Contribute to mokata (developers only)¶

Only clone if you're working on mokata itself; end users never need to.

git clone https://github.com/JasGujral/mokata-oss.git
cd mokata-oss
pip install -e .            # editable install (Python 3.10+ also pulls the MCP SDK)
python -m unittest discover -s tests -t tests

Installing in an isolated environment¶

pipx keeps mokata off your global Python:

pipx install mokata
pipx upgrade mokata         # when a new version ships

Homebrew is isolated the same way — the formula builds mokata its own virtualenv:

brew install JasGujral/mokata/mokata
brew upgrade mokata         # when a new version ships

Zero-install runners also work: uvx mokata --version.

Trying a pre-release¶

Release candidates are published to PyPI but not installed by default — plain pip install mokata always gives you the latest stable. To test a candidate:

pip install --pre mokata            # newest pre-release
# or pin an exact candidate (see the PyPI release history for the tag):
pip install "mokata==<version>rc1"

Once you've validated it, move back to the stable line with pip install -U mokata.

What's next¶

New to the workflow? Run mokata tour for a 60-second read-only walkthrough.
See the full command list in the CLI reference.

The mokata Claude Code plugin installs today from mokata's own marketplace (Path A1). A listing in Claude's community plugin marketplace is pending submission — until it exists, use the two /plugin commands above.