The memory + seatbelt for your AI coding agent. Spec-driven TDD for Claude Code — knowledge-aware, self-healing memory, human-gated, local-first. It remembers your project and stops the agent shipping the wrong thing.

📖 Full documentation: https://mokata.ai/ — quickstart, tutorials, concepts, and the complete CLI + plugin reference. ▶ See it moving: the skills tour video · the 60-second seatbelt demo

Install

One install line, one setup. Run them in your repo:

uv tool install "mokata[full]"         # mokata + everything full mode uses, fetched by the installer
mokata setup claude --mode full        # detects and wires it all — installs nothing
# restart Claude Code, then check:
mokata doctor

Same with pipx: pipx install "mokata[full]" · with pip (inside a dedicated venv): pip install "mokata[full]". Updating later: uv tool upgrade mokata (or pipx upgrade mokata) keeps the extra, then re-run mokata setup claude --mode full. Or just mokata update: it shows the release notes and that command, asks once, and does both.

mokata[full] bundles the local semantic-memory model runtime, the code-review-graph structural graph, the TypeScript parser and the IDE companion's web stack (about 360 MB, all local, no API key). --mode full never rebuilds its own environment: it switches the semantic tier on, warms the model (a ~30 MB one-time download from huggingface.co — if that is blocked, it says why), and pins code-review-graph as the code graph. It ends with a table of what is active and, for anything that is not, the cause and the ONE line that fixes it for the installer you used. Prefer less? --mode seatbelt (just the gates) or --mode memory (gates + persistent memory, with mokata[embeddings]).

mokata setup claude runs mokata init for you on a repo that has no .mokata/ yet, and on a repo that has one it leaves your config, memory and ledger alone and refreshes only the wiring — new commands (e.g. /review-window) appear and stale ones are removed. Re-run it after every upgrade. Needs uv (or pipx) and Python ≥ 3.12; mokata gets its own environment, never your project's, and works on your existing Claude Code sign-in — no API key. Requires Claude Code ≥ 2.1.198 — mokata doctor names any feature an older one lacks.

Or, entirely inside Claude Code · the plugin — two in-app commands, no pip, no terminal:

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

The plugin runs everything — its MCP server, its hooks, /mokata:doctor and the review window (/mokata:review-window, the IDE preview) — from ONE pinned environment, uvx --from "mokata[full]==<plugin version>", so the plugin and the Python package can never be different versions. It needs uv (not Python: uv fetches one if you have none); without it, the first session tells you the one install line for your OS. The first start fetches mokata[full] once (about 100 packages, ~400 MB in uv's cache — seconds on a fast link, minutes on a slow one); if /mcp shows mokata failed meanwhile, reconnect it when the download ends. Finish full mode in a repo with the one command the first briefing names: uvx --from "mokata[full]==<plugin version>" mokata setup claude --mode full --plugin (or ask /mokata:init full). /mokata:doctor checks the route: uv found · package resolved · versions match · MCP server running · hooks firing.

Which to choose. Live in Claude Code and want nothing on your PATH → the plugin. Want the mokata command in your terminal too (CI, scripts, mokata ide from a shell, other AI tools) → uv tool install "mokata[full]". Both end in the same full mode — code graph, search by meaning, lexical search, the gates. Use one route per repo; if both are wired, the CLI route's hooks take over and the plugin's stand down. Plain pip install mokata also works, but inside a project venv this mixes mokata's deps into yours; mokata doctor warns when it finds that, or an older copy shadowing it on PATH.

Every route, step by step: Getting started · Install mokata · Integrate with other AI tools.

Installs today as a Claude Code plugin from mokata's own marketplace — inside Claude Code run /plugin marketplace add JasGujral/mokata-oss, then /plugin install mokata@mostack (the plugin starts its MCP server through uvx, so uv must be on PATH). ⏳ Pending: the community-marketplace listing (pending submission) — mokata is not yet listed in Claude's community plugin marketplace; until it is, use the two commands above. (This notice auto-flips once the listing exists — single source: scripts/directory_listing.py.)

Contributing (developers). 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 . (this also pulls the MCP SDK). See CONTRIBUTING.md.

---

See it catch a bad change (30 seconds)

An AI agent, mid-task, tries two bad changes — ship code with no spec, and stash an AWS key while waving its own write through. mokata stops both. (Real output; run it yourself with mokata init --profile standard --yes in a scratch repo.)

$ mokata run develop          # the agent tries to write code with no spec...
[BLOCKED] spec-persisted — no saved spec — draft and emit it first (/spec); the completeness gate must pass before implementation.

$ # ...then tries to stash a secret, approving its own write with approve=True:
status: proposed   committed: False
`approve`/`confirm` no longer commit: an approval is MINTED BY A HUMAN out-of-band (`mokata approve <id>`) and can only be REFERENCED here by id. Typing approve=true is not consent — it never was.

$ mokata audit                # the gate decision is on the ledger
audit ledger — 1 entry:
  #1   gate        gate=spec-persisted phase=develop decision=blocked reason=no saved spec ...

A model cannot approve its own writes at all. It can only propose one and hand you an id; the approval is minted by you, out-of-band, in a process the model isn't driving — and it is single-use, content-hashed, and expires. And if you do approve that write, the secret-guard still refuses it: approval is a methodology gate, never a security override.

There is a third block the agent can't route around either — reaching past mokata's tools for the editor's own Write trips a PreToolUse hook (exit 2) and the file is never touched. It's in the full demo.

The full copy-paste demo + a 60-second screencast script: mokata catches a bad change. See every differentiator run in differentiators in action.

---

See mokata in action

A quick tour of the workflow and skills — brainstorm → spec → test → develop → review → ship, with governance, memory, and the always-on status badge.

skill_description.video.mp4

▶ Video not playing inline? Watch it here.

---

mokata is an open-source framework for Claude Code that brings the best ideas in AI-assisted coding into one governed, knowledge-aware engine. At its core is a spec-driven TDD engine that starts by brainstorming the problem with you — one question at a time, weighing two or three real approaches grounded in your actual codebase before committing to anything. Only then does it draft a spec, and no code is written until that specification passes a provable completeness gate, every acceptance criterion is statically mapped to a test (RED before GREEN), and the finished code is reviewed back against the spec. Around that engine, mokata builds in the layers a single tool usually leaves out — a persistent codebase knowledge graph so the agent navigates by structure instead of guessing, persistent, self-healing memory (decisions, conventions, and past conversations that survive across sessions and surface their own contradictions instead of silently rotting), and active token-and-cost governance that retrieves just what's needed rather than dumping files into context. Memory and its self-healing ship as part of the framework, on by default — not an add-on you wire up. It can also orchestrate the external tools you already trust — like code graphs — under one set of gates with a full audit trail, and every durable write, whether to code, memory, or config, is human-gated: nothing silent, nothing autonomous. And it's fully configurable and composable — switch any layer or tool on or off, pick a profile, or reach for a single capability on its own: generate tests, debug a failure, or review a diff as a standalone command or directly-invoked skill, entering the pipeline wherever you need rather than running the whole thing. mokata is local-first, phones home nothing by default, is Apache-2.0 licensed, and is built so you can review every decision it makes.

Naming: mokata = the framework · MoStack = the brand it ships under.

Why mokata

• Spec-driven, provable completeness. No code ships until every acceptance criterion maps to a test (RED before GREEN). The completeness gate blocks emit — it never silently passes.
• Knowledge + memory built in. A codebase knowledge graph (adopted, with an embedded stdlib-AST floor beneath it and grep below that) and persistent, self-healing memory (on by default) — the agent navigates by structure and remembers decisions across sessions.
• Governed by default. Every durable write (code, memory, config) is human-gated — the model proposes, you mint the approval out-of-band (mokata approve <id>; single-use, content-hashed). Sync hooks block (exit 2), async hooks observe: two sync blocks ship and they differ in kind — the secret-guard (security; never overridable) and the gate-guard (run-state/methodology; overridable with a reason, on the ledger). Every gate decision and tool call lands in an append-only audit ledger.
• Local-first, no telemetry. Nothing leaves your machine unless you explicitly wire an external service. The minimal profile performs zero network egress.
• Configurable & composable. Toggle any layer/tool, pick a profile, run any capability standalone, and enter the pipeline from any phase.
• Meets you where you work, ships trustworthy. Runs under Claude Code, Cursor, Copilot, Windsurf, Codex, Gemini CLI, and Aider (a VS Code extension is planned, not yet available); sessions travel between machines; teams share one governed backend safely; and releases carry an SBOM + Sigstore provenance — no telemetry, ever.

Quickstart

In Claude Code (primary) — after mokata setup claude, drive the workflow with slash commands (installed as the plugin, the same commands are namespaced: /mokata:<name>):

/brainstorm        # Socratic pre-spec exploration (HARD-GATE before any spec)
/spec              # draft the spec (blocked until every acceptance criterion maps to a test)
/test  /develop    # RED-before-GREEN
/review            # spec-compliance, then quality

Or via the CLI (outside Claude Code):

mokata init                         # scaffold .mokata/ (default profile: standard); human-gated
mokata init --mode seatbelt         # or start graduated: seatbelt | memory | full
mokata brainstorm                   # Socratic pre-spec exploration (HARD-GATE before spec)
mokata playbook                     # drive the full story end-to-end through the pipeline

--mode {seatbelt,memory,full} is a graduated adoption on-ramp — a named alias for a profile plus a printed 5-minute quickstart, mutually exclusive with --profile. seatbelt gets you the gates (and the AST code graph they need), memory adds typed persistent project memory, full wires everything; memory/full additionally offer the optional local embeddings model when run interactively. Only the profile is persisted — the mode is an on-ramp, not a second config axis. See Getting started.

A pip CLI install is terminal-only — it runs the deterministic engine with no LLM attached. It does not put mokata inside Claude Code; for that, install the plugin or run mokata setup claude. (Why two ways.)

mokata init = your repo (.mokata/). mokata setup claude = your agent (.claude/, and it runs init for you). ⚠ Since 0.0.19 the non-interactive mokata init --yes does both — it wires the harness too, which matters if you call it from CI. Upgrading? The same instruction as setup — mokata update (or uv tool upgrade mokata, then mokata setup claude), which refreshes the wiring and keeps your config; a package upgrade alone leaves the old wiring in place. Decision table + upgrade runbook: Which setup command do I need?

Full walkthrough: docs/quickstart.md · full hands-on guide → the Complete Guide (with a downloadable PDF) · published docs: https://mokata.ai/

Core concepts

• 7-phase pipeline + gates — brainstorm → analysis → strawman → pre-mortem → probes → completeness gate → emit; enter at any phase, each phase's gates still apply.
• Knowledge layer — structural queries (callers/callees/imports/blast-radius) via an adopted graph, with an embedded stdlib-AST floor when none is adopted (grep beneath that); staleness is surfaced, never served silently.
• Memory — persistent / decision / episodic, on by default, self-healing by surfacing old→new diffs for your approval (never a silent rewrite).
• Execution modes — sequential gated flow (default, lowest-cost) or parallel subagents (fresh-context isolation + two-stage review, concurrent fan-out), chosen per run, degrade-safe; optional git-worktree isolation keeps concurrent/paused work off the main tree.
• Governance & audit — 4-tier rules, Karpathy gates, 4-layer secret protection, per-task model routing, reversible writes, full audit ledger. Inside an active run, four run-state gates stop the agent's own file writes in Claude Code — approach-approval (still in brainstorm, no approach approved), spec-persisted (no spec yet), no-code-without-failing-test (no RED on record), and spec-scope (outside the spec's authorized surface, or a feature you agreed not to build). Test files stay writable; hand-editing outside a run is never policed; mokata gate status shows what's enforced and mokata gate override <gate> --reason "…" lifts one, on the ledger. See the governed state at a glance with mokata govern (a read-only dashboard) and the what-it-did-and-why timeline with mokata audit --why.
• Session lifecycle & portable sessions — list runs (mokata sessions), resume from the last passed gate (mokata resume), pause/resume a mid-brainstorm (the HARD-GATE still holds), snapshot the in-flight session with mokata session save (local, ungated), and carry it across machines or hand it to a teammate: mokata session push <tag> / pull <tag> packages checkpoints + approach + in-progress brainstorm + relevant memory into a machine-path-free, versioned, secret-scanned + human-gated bundle (--save-first to snapshot and bundle in one step; sharing unfinished thinking needs an explicit --allow-in-progress, or --requirements-only to hand over just the distilled requirements). An approach approval never crosses machines — pull strips it, so you re-approve here (the emitted spec travels intact). Sessions carry a human-friendly name you can session name.
• Progress & visibility, one model — one RunProgress drives every surface: an always-on stage badge (statusline, on by default, merge-safe), the native to-do widget where the harness has one, the printed run-progress block, and the per-subagent lanes in mokata watch / progress --lanes. No duplicated progress logic — channel-specific renderers over one source of truth.
• Runs under every agent, shows up in your editor — the engine runs behind a thin boundary (mokata harness shows the capability matrix) with in-harness surfaces for Claude Code, Cursor, GitHub Copilot, Windsurf, Codex, Gemini CLI, and Aider, each degrading clearly where it lacks a capability. A VS Code extension (editors/vscode) with a read-only Copilot Chat @mokata participant — governance, memory, and run-progress in your editor — is planned (not yet available).
• Team & sharing — one guided mokata team join chains adopt → shared memory (BYO Postgres) → vault pull → onboard → doctor (each human-gated, secret-scanned, reversible); publish/adopt governed per-framework community stacks (mokata stacks); and the team's audit/activity logs can live shared or local, conflict-free — no telemetry, nothing phoned home. One shared backend safely hosts many projects: every shared row is scoped by a stable project key, so review defaults to your project (--all / --project to span or pick).
• Supply-chain trust — releases ship a reproducible sdist+wheel, a CycloneDX SBOM, and a Sigstore build-provenance attestation generated at tag-time in CI (the repo ships no pre-signed artifacts); all five CI workflows are least-privilege and SHA-pinned.

Profiles & configuration

Profile	Layers	Capabilities	Network
minimal	engine, governance	none (engine only)	zero egress
standard (default)	+ knowledge, memory	code graph (ast→ripgrep→grep) + memory (SQLite)	local-only
full	all	every known graph + memory provider (degrade to floors)	only present tools, all gated

Per-layer / per-tool toggles, the trust dial (per write surface or per tool — enforced today on the MCP write surface), and profiles are all in the committed manifest. See docs/profiles.md.

Commands & skills

mokata skills lists the catalog — 16 curated skills Claude can auto-engage (each also a slash command — bare /<name> on the pip + mokata setup claude route): the pipeline (brainstorm, refine, onboard, spec, test, develop, review, debug, optimize, bug, ship) plus standalone/auto-firing govern, session, playbook, docsync (docs↔code reconciler, human-gated fixes), and mcp-repair — and 14 domain-knowledge skills (API design, security, performance, frontend/accessibility, browser testing, CI/CD, git workflow, deprecation, docs/ADRs, shipping, plus React, NestJS, frontend performance and frontend security) that attach to the pipeline phase where they apply. Utilities like version stay CLI-only.

The CLI exposes 69 subcommands, including:

• Pipeline & skills — brainstorm, spec (show/amend), test, develop, review, ship, refine, debug, bug, optimize, onboard, plus run/enter/exec/playbook (--dense)/preview/chain and skill author.
• Approvals & gates (the seatbelt) — approve [<id>] (mint the approval for a proposed write in your terminal; bare approve lists what's pending. There is no approve slash command; the in-chat MCP approve tool (mcp__mokata__approve) is opt-in and default-OFF, and even when enabled Claude Code prompts you on every call — the model never mints its own consent unprompted) and gate (status/override/clear — the run-state gates; an override needs a reason and is ledgered).
• Inspection (read-only) — status, query, rules, audit (--why), budget, coverage, lat-check, index, doctor, baseline, harness, progress (--lanes), watch, govern, sessions, windows (concurrent Claude Code windows on one repo).
• Memory & knowledge — memory (edit/export/import/migrate/reembed/consolidate/promote/review), govern.
• Session lifecycle & portability — sessions, resume, enter, session (save/push/pull/list/name), worktree create (give a window its own working tree).
• Team, stacks & sharing — team (init/join/adopt/connect/disconnect), mode, sync, stacks (list/search/show/install), vault.
• Setup, config & distribution — init, setup/unsetup, reconfigure, tour, config, bootstrap, validate, route, detect, reset, suggest, mcp, ci-check, export/import, version/update, release-check.

Full list with flags: the CLI reference.

Contributing · Security · License

• CONTRIBUTING.md — dev setup, the clean-room rule, tests in both jsonschema states.
• SECURITY.md — how to report a vulnerability (privately).
• CODE_OF_CONDUCT.md — Contributor Covenant.
• LICENSE — Apache-2.0, © MoStack. mokata is built clean-room (no dependency on any other framework).

Links

• Documentation: https://mokata.ai/ (the published docs site; source in docs/, built with MkDocs)
• Changelog: CHANGELOG.md
• Issues & discussions: the repository's Issues / Discussions tabs