Skip to content

How-to: install the Claude Code plugin

⏳ Pending Claude plugin-directory approval. A one-click Claude Code plugin is planned, not yet available — mokata isn't registered on any Claude Code marketplace. The supported way to run mokata inside Claude Code today is the pip-first path: pip install mokata → mokata setup claude (see Getting started). (This notice auto-flips once the listing is approved — single source: scripts/directory_listing.py.)

The rest of this page is an experimental/advanced note for the manual /plugin marketplace add route from a local checkout — see also Use mokata without the plugin.

The plugin is just a convenient bundle of the same artifacts mokata setup claude writes. If you want to try the manual marketplace route from a local clone (advanced), /plugin marketplace add <path> reads the .claude-plugin/marketplace.json in that directory and registers it as a local marketplace named mostack:

# experimental / advanced — from a local clone:
/plugin marketplace add ~/path/to/mokata-oss
/plugin install mokata@mostack

The @mostack handle is the local marketplace name. (A public marketplace submission is a separate, later step for discoverability — it is not live yet.)

Command form ↔ install route. The namespaced /mokata:<name> form below is the plugin render. Via the pip-first mokata setup claude path (the supported route today) the same commands appear bare in your / menu — /<name> (drop the mokata: prefix).

Either the supported setup path or the experimental route makes the slash commands available — /mokata:brainstorm, /mokata:spec, /mokata:test, /mokata:develop, /mokata:review, /mokata:debug, /mokata:optimize, /mokata:bug — and wires its hooks (declared in hooks/hooks.json):

  • SessionStart → hooks/session_start.py (async/observability) — injects the bootstrap briefing.
  • PreToolUse → hooks/secret_guard.py (sync security, exit code 2, matcher Write|Edit|MultiEdit|Bash) — blocks a write or shell command carrying a secret. Never overridable: no approval, and no flag, lifts it.
  • PreToolUse → hooks/gate_guard.py (sync methodology / run-state, exit code 2, matcher Write|Edit|MultiEdit|NotebookEdit) — blocks a write that breaks the run's discipline: approach-approval, spec-persisted, no-code-without-failing-test, spec-scope. Overridable — but only explicitly, by a human: mokata gate override <gate> --reason "<why>", re-confirmed interactively, scoped to that session, and written to the audit ledger. There is deliberately no env-var kill switch, no MCP tool, and no slash command for it.
  • PostToolUse → hooks/dirty_track.py (async/bookkeeping, matcher Write|Edit|MultiEdit|NotebookEdit) — records touched paths into the session graph dirty-set so the code graph is reconciled before the next query answers. It never blocks (always exits 0).

The two PreToolUse guards are sync blocks, and they differ in kind: security is absolute, methodology is accountable. The gate-guard fires only inside an active mokata run, and never on a test file — you must be able to write the failing test.

Confirm the exact install handle in .claude-plugin/marketplace.json. To verify the install: the / commands appear, the SessionStart hook injects the briefing, planting a secret in a tool input is blocked by secret_guard (exit 2), and — mid-run, before a failing test — an implementation write is blocked by gate_guard (exit 2).

Want just the terminal CLI? pip install mokata puts the mokata command on your PATH:

pip install mokata
# or, on macOS/Linux:
brew install JasGujral/mokata/mokata

Heads up: pip install alone gives you the mokata command in your terminal only — it does not put mokata inside Claude Code (no slash commands, no hooks). For the in-Claude workflow, run mokata setup claude (the supported path — see Getting started). Why two ways: How mokata uses an LLM: harness vs CLI.

See the CLI reference. To get the full workflow (slash commands, tools, hooks) inside Claude Code without installing the plugin — or to wire mokata into another harness — see Use mokata without the plugin.