Skip to content
mokata 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.

★ Star on GitHub Get started
mokata · story-042 · live 
$ pip install mokata && mokata setup claude
$ mokata run story-042

✓ spec drafted          7 acceptance criteria
✓ ac → test map         7/7 mapped · completeness gate
✓ red gate              7 tests failing — as they should
✓ green                 42 passed · 0 skipped
✓ spec compliance       reviewed against spec
⏸ human gate            approve durable writes? [y/N]
// see it in action

Skills, explained in one video

// get running in 60s

Install, wire, run

$ pip install mokata && mokata setup claude

One package, zero required dependencies. mokata never calls a model itself — the brain always comes from your harness.

// what mokata gives you

One governed engine

≡ spec

Spec-Driven Pipeline

Brainstorm → spec → tests → code → review. Seven phases, each gated. No code is written until every acceptance criterion maps to a test.

7 phases · gated
✗→✓ tdd

RED Before GREEN

Tests must fail first. mokata proves the test can catch the bug before the implementation exists — no vacuous green suites.

provable tdd
◉ graph

Codebase Knowledge Graph

An adopted code graph with typed queries, incremental indexing, staleness detection, and drift anchors — with a grep floor as fallback.

typed queries · incremental
∞ mem

Self-Healing Memory

Persistent, decision, and episodic memory that surfaces itself when relevant and consolidates over time. Pluggable backends. On by default.

on by default
⏸ gate

Human-Gated Writes

Every durable write — memory, graph, rules, code — stops at a gate you approve. The agent proposes; you decide.

you approve · always
Σ tokens

Token Governance

Active tracking, JIT retrieval, handback caps, output-density control, and cache-stable prefixes. Budgets, not vibes.

budgeted · measured
⌂ local

Local-First & Private

Nothing leaves your machine unless you wire it. mokata never calls a model itself — the brain always comes from your harness.

zero exfiltration
≣ audit

Full Audit Trail

Every gate decision, rule application, and durable write is recorded. Reconstruct any run — what changed, why, and who approved it.

traceable runs
∅ deps

Zero Dependencies

Pure Python ≥ 3.9 with no required runtime dependencies. Apache-2.0, clean-room, works with Claude Code, CLI, Gemini, Codex, or CI.

pip install mokata

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 knowledge graph, persistent self-healing memory (on by default), active token governance, and a full audit trail — with every durable write human-gated and nothing leaving your machine unless you wire it.

mokata is pure Python (≥ 3.9), has no required runtime dependencies, 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 (CONNECTED ✓). 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:

The feature set at a glance

Part Area Highlights
A Spine manifest, capability router, detection + graceful degradation, bootstrap, init
B Knowledge adopted code graph + grep floor, typed queries, incremental index + staleness, drift anchors
C Memory persistent / decision / episodic, self-healing (surfacing), pluggable backends, consolidation
D Engine 7-phase pipeline, provable completeness gate, AC-mapper, pre-mortem, spec-compliance, dry-run
E TDD & execution RED-before-GREEN, model routing, bug/debug/optimize engines, execution-mode selector
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-gated writes, audit ledger, lethal-trifecta gate, revert, resume
J Distribution plugin/marketplace packaging, cross-harness boundary, shareable stack manifests
K Config per-layer/tool toggles, profiles, local-first, committed config, trust dial, doctor, reset
L Composability standalone commands, mid-pipeline entry, direct skills, catalog, chaining, suggestions

Published docs: https://jasgujral.github.io/mokata-oss/ · Source & issues: https://github.com/JasGujral/mokata-oss.