open source · spec-driven tdd · claude code
The memory + seatbelt
for your AI coding agent.
mokata refuses to write code until every acceptance criterion maps to a failing test — RED before GREEN — then reviews the result back against the spec. Around the engine: a codebase knowledge graph, self-healing memory, token governance, and a full audit trail. Every durable write human-gated. Nothing leaves your machine.
pip install mokata && mokata setup claude
$ pip install mokata && mokata setup claude $ mokata init --mode seatbelt ✓ approach approved prior-art step ran · scope bound ✓ spec persisted 7 acceptance criteria ✓ ac → test map 7/7 mapped · completeness gate ✓ red gate 7 tests failing — as they should ✓ green 42 passed · 0 skipped ✓ review checked back against the spec ⏸ AWAITING APPROVAL waiting on a human — not an error
Your agent is the fast car.
mokata is the seatbelt — and the black-box recorder.
Why not just prompts and rules files? Because they're advice — a model can ignore them, and you'll never know it did. mokata's gates are code: a hook that blocks the write, an approval only a human can mint, a ledger that records every decision. Structure, not suggestion.
Skills, explained in one video
The skills tour — what ships in the box, in motion.
Install, wire, run
One package, one runtime dependency — the MCP SDK, so the server works out of the box. mokata never calls a model itself — the brain always comes from your harness.
One governed engine
Codebase Graph — Mandatory by Default
Blast radius is answered structurally, not by grep. An embedded stdlib-AST floor ships in the box (no adoption step), and adopted graphs layer on top. A degraded answer is refused as decision input unless you accept a ledgered, session-scoped escape — and a graph mokata knows is stale rebuilds before it answers, never serving you old structure.
ast floor · degrade refusedMemory That Can't Be Poisoned
Typed, governed memory — rules, guardrails, decisions, context — that surfaces itself when relevant. There is no code path that writes memory without a human-minted approval, so it cannot be poisoned by content you never approved. The defense is structural, not a filter.
no auto-writes · typedMemory That Ages — Without Losing Anything
Items carry usage signals and bi-temporal validity windows. An over-budget scope gets a proposed archival sweep, coldest first — and archiving closes a window rather than deleting a row, so what you archive stays re-openable and provenance survives. Two people writing the same fact produce a proposal, not a lost fact.
bi-temporal · never deletesRetrieval That Tells the Truth
Lexical recall ranks in the database (SQLite FTS5 + bm25, Postgres tsvector + ts_rank), and each tier nominates its own shortlist there, so recall doesn't slow down as your store grows. A real semantic tier installs on consent. Both degrade independently — and mokata doctor names which engine is actually ranking your recall.
Every Decision, Reviewed
Every gate verdict, rule application, and durable write is recorded. Reconstruct any run — what changed, why, which criterion it served, and who approved it.
traceable runsLocal-First & Private
Nothing leaves your machine unless you wire it. mokata never calls a model itself — the brain always comes from your harness. Even memory summaries are drafted by the agent you're already talking to: no model is embedded in mokata, and no API key is involved.
zero exfiltrationA Structural Seatbelt
Four run-state gates are enforced by a hook, so they hold for your agent's native edits — not just mokata's own tools. No approved approach, no persisted spec, no failing test, or a write outside the scope the spec authorized, and the write is blocked outright. Ahead of all four, self-protect refuses any write to an installed package tree or outside your workspace.
Spec-Driven Pipeline
Brainstorm → spec → test → develop → review → ship, each stage gated. Brainstorm alone runs seven gated phases before it will emit a spec. A deferred item can't be built later without a re-gated spec amendment.
gated stages · scope-boundRED Before GREEN
Tests must fail first. mokata proves the test can catch the bug before the implementation exists — no vacuous green suites.
provable tddHuman-Minted Approval
Every durable write stops at a gate you approve. Approvals are single-use, content-bound and expiring, minted by you — the model cannot type its own consent. An in-chat approve tool exists but ships off by default.
you approve · alwaysWaiting Is Legible, Not Silence
Every MCP call is bounded — 60s interactive, 120s for baseline — and an overrun returns a timed_out status naming the operation. A gated write says AWAITING APPROVAL: waiting on a human, this is not an error. You can always tell waiting from stuck.
Adopt It Gradually
mokata init --mode seatbelt gives you the gates and the graph. --mode memory adds typed persistent memory. --mode full turns on everything. Each mode prints the quickstart for that step — you never swallow the whole framework on day one. And mokata upgrade finishes the job a pip install -U starts: it refreshes the harness wiring through the same preview-diff gate, so a gate added since your last setup can't be silently absent.
Token Governance
Active tracking, JIT retrieval, handback caps, output-density control, and cache-stable prefixes. Budgets, not vibes.
budgeted · measuredOne Dependency
Pure Python ≥ 3.10. The engine is stdlib-only and the MCP SDK is the single runtime dependency, so the MCP server works out of the box. Apache-2.0, clean-room, and it runs from Claude Code, the CLI, Gemini, Codex, or CI.
pip install mokataAt a glance
16 curated · 10 domain
wired into Claude Code
harness-independent
40 read · 20 write · 1 approve
5 enforced on native writes
the MCP SDK
Put the seatbelt on.
pip install mokata && mokata setup claude
About mokata¶
mokata is an open-source framework for Claude Code that brings the strongest ideas in
AI-assisted coding into one governed engine. It brainstorms the problem with you, drafts a
spec, refuses to write code until every acceptance criterion maps to a test (RED before
GREEN), and reviews the result back against the spec. Around that engine sit a codebase
graph that is mandatory by default (an embedded stdlib-AST floor ships in the box, so
blast radius is answered structurally rather than by grep), typed persistent memory with
in-database lexical recall and an optional consented semantic tier, active token governance,
and a full audit trail — with every durable write human-gated (the model proposes; you
mint the approval in your own terminal with mokata approve <id> — a model can never approve
its own write) and nothing leaving your machine unless you wire it.
Five of those gates are enforced by a hook rather than by mokata's own tools, so they hold for
your agent's native edits too: no approved approach, no persisted spec, no failing test, or a
write outside the scope the spec authorized, and the write is blocked outright — and ahead of all
four, self-protect refuses any write to an installed package tree or outside your workspace at
all. And because no code path writes memory without a human-minted approval, mokata's memory
cannot be poisoned by content you never approved.
You don't have to adopt all of it at once — mokata init --mode seatbelt wires just the gates
and the graph, --mode memory adds persistent memory, --mode full turns on everything.
mokata is pure Python (≥ 3.10) — the engine is stdlib-only, and the MCP SDK is its single runtime dependency, so the MCP server works out of the box. It is Apache-2.0 under MoStack, and is built clean-room (no dependency on any other framework).
Start here → Getting started. The canonical, pip-first path:
pip install mokata → mokata setup claude → restart Claude Code → mokata mcp status
(REGISTERED ✓ with connected ✓ under it). That one command wires the full workflow (slash commands + Agent Skills + MCP
server + status line) into Claude Code. Prefer the terminal or another AI tool? The same
pip install mokata gives you the CLI (Gemini, Codex, scripts, CI). A one-click Claude
Code plugin is planned but not yet available.
mokata never calls a model itself — the brain always comes from the harness. For why there are two ways to run it (and which fits your goal), see How mokata uses an LLM: harness vs CLI.
What's here¶
This site follows the Diátaxis model:
- Getting started — install and run your first pipeline in minutes.
- Tutorials — mokata catches a bad change: a 60-second copy-paste walkthrough — run it in your own terminal and watch the seatbelt catch a bad change; differentiators in action: a runnable demo of every differentiator (graph, memory, governance — see them work); run a story end-to-end: a guided, learn-by-doing walkthrough; and the Complete Guide: every command, gate, and layer (with a downloadable PDF).
- How-to guides — task recipes: configure a profile, set the execution mode, use & heal memory, write a skill, integrate other tools, share a stack, run mokata as a team (setup & operations), install the Claude plugin, use mokata without the plugin.
- Concepts — how each layer works: the pipeline & gates, knowledge layer, memory, token governance, execution modes, governance & audit.
- Reference — complete specs: CLI, manifest & configuration, skills catalog.
- Developer guide — architecture, dev setup, testing, contributing.
The feature set at a glance¶
| Part | Area | Highlights |
|---|---|---|
| A | Spine | manifest, capability router, detection + graceful degradation, bootstrap, init (incl. the --mode seatbelt\|memory\|full on-ramp); upgrade refreshes the harness wiring through setup's own preview-diff gate, and stale wiring is visible on three channels (doctor --wiring exits non-zero, and works before init) |
| B | Knowledge | codebase graph mandatory by default — embedded stdlib-AST floor in the box, adopted graphs layered on top, grep beneath; a degraded blast radius is refused as decision input unless a ledgered escape is accepted; typed queries, incremental index + staleness, drift anchors |
| C | Memory | typed persistent / decision / episodic memory, self-healing (surfacing), no auto-writes — the poisoning defense; in-database lexical recall (SQLite FTS5 + bm25, Postgres tsvector + ts_rank) with an optional consented semantic tier, doctor reporting which is live; it ages — usage signals + bi-temporal validity windows, and an over-budget scope gets a proposed archival sweep that closes a window rather than deleting a row; it stays fast as it grows — each tier nominates its shortlist in the database; two people writing the same fact produce a proposal, not a lost fact; summaries are drafted by the agent you are already talking to (no model embedded, no API key) and still gated; memory export/import backs it up to .mokata/backups/ |
| D | Engine | brainstorm → spec → test → develop → review → ship, each gated (brainstorm alone runs 7 gated phases); provable completeness gate, AC-mapper, pre-mortem, prior-art step, spec-compliance, dry-run; a deferred item needs a re-gated spec amend before it can be built |
| E | TDD & execution | RED-before-GREEN, model routing, bug/debug/optimize engines, execution-mode selector; a run can take its own worktree and branch — always offered, never automatic — and worktree list joins your worktrees against their sessions with a staleness verdict per row |
| F | Token governance | tracker, JIT retrieval, handback caps, output density, budget, cache-stable prefixes |
| G | Rules & governance | 4-tier rules, taxonomy, sync/async hooks, Karpathy gates, rule-learning, skill authoring |
| I | Safety & audit | secret protection, human-minted single-use approvals, 9 backed gates — and the hook stops 5 things on your agent's native writes (self-protect plus the four run-state gates), audit ledger, lethal-trifecta gate, revert, resume |
| J | Distribution | cross-harness boundary, shareable stack manifests, portable sessions (transport derived from the repo's mode); release-notes-check refuses the cut when the notes announce a different version than the tag, or quietly drop a fact the changelog declared as a known limitation |
| K | Config | per-layer/tool toggles, profiles, local-first, committed config, trust dial, doctor (incl. the DSN deep-check and retrieval-stack line), reset |
| L | Composability | standalone commands, mid-pipeline entry, direct skills, catalog, chaining, suggestions |
| M | MCP surface | 61 tools (40 read · 20 write · 1 opt-in approve), every call bounded with a timed_out status that names the operation, typed annotations, structured response_format, cursor pagination, and a loud AWAITING APPROVAL head so waiting-on-a-human never reads as a hang |
Counts in the box today: 26 Agent Skills (16 curated + 10 domain) · 37 slash commands · 69 CLI subcommands · 61 MCP tools · 9 backed gates · 1 runtime dependency.
Published docs: https://mokata.ai/ · Source & issues: https://github.com/JasGujral/mokata-oss.