mokata 0.0.9rc1

An open-source, spec-driven TDD framework for Claude Code — governed, knowledge-aware, human-gated.

mokata

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://jasgujral.github.io/mokata-oss/ — quickstart, tutorials, concepts, and the complete CLI + plugin reference.

---

See it catch a bad change (30 seconds)

An AI agent, mid-task, tries two bad changes — ship code with no spec, and stash a secret. mokata stops both, and puts both on the audit ledger. (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 (/mokata:spec); the completeness gate must pass before implementation.

$ # ...and tries to stash a secret (even with approve=True):
status: blocked   findings: ['aws-access-key', 'high-entropy-token', 'sensitive-location']

$ mokata audit                # every block is on the ledger
audit ledger — 2 entries:
  #1   gate        gate=spec-persisted phase=develop decision=blocked reason=no saved spec ...
  #2   write_gate  write_kind=memory target=memory:aws.key actor=mcp decision=blocked reason=secret detected

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.

https://github.com/user-attachments/assets/a6940119-1edb-4017-b935-cd48b80b4ea9

▶ 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 a grep floor) 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; sync hooks block only for security (exit 2), async hooks observe; 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 in 0.0.9); sessions travel between machines; teams share one governed backend safely; and releases carry an SBOM + Sigstore provenance — no telemetry, ever.

Install

Start here → Getting started. The canonical, pip-first path.

In Claude Code (recommended) — one install, then one command wires the full workflow (slash commands + Agent Skills + MCP server + status line), on your existing Claude Code sign-in — no API key:

pip install mokata               # MCP server works out of the box on Python ≥ 3.10 (SDK is a default dep)
mokata setup claude              # wires commands + skills + MCP + statusline — human-gated
# restart Claude Code, then:
mokata mcp status                # expect: mokata-mcp: CONNECTED ✓

On Python 3.9 the MCP server is unavailable (it needs ≥ 3.10) — the CLI and everything else still work.

As a CLI, with any AI tool — harness-agnostic (Gemini, Codex, scripts, CI). The CLI is the engine's mechanics (no LLM of its own); wire it into any shell- or MCP-capable assistant:

pip install mokata
mokata init

See Integrate with other AI tools.

⏳ 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.)

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 . (on Python ≥ 3.10 this also pulls the MCP SDK). See CONTRIBUTING.md.

Quickstart

In Claude Code (primary) — after mokata setup claude, drive the workflow with slash commands:

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

Or via the CLI (outside Claude Code):

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

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.)

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

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, grep floor when absent; 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. 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), and carry a session 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. Sessions carry a human-friendly name you can rename.
• 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 in 0.0.9).
• 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 (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, per-adapter trust dials, and profiles are all in the committed manifest. See docs/profiles.md.

Commands & skills

mokata skills lists the catalog. Skills (each a /mokata:* command): brainstorm, refine, onboard, spec, test, develop, review, debug, optimize, bug, ship, version.

The CLI exposes 40+ subcommands, including:

• Pipeline & skills — brainstorm, spec, test, develop, review, ship, refine, debug, bug, optimize, onboard, plus run/enter/exec/playbook (--dense)/preview/chain and skill author.
• Inspection (read-only) — status, query, rules, audit (--why), budget, coverage, lat-check, index, doctor, baseline, harness, progress (--lanes), watch, govern, sessions.
• Memory & knowledge — memory (edit/export/import/migrate/consolidate), govern.
• Session lifecycle & portability — sessions, resume, enter, session (push/pull/list/name).
• Team, stacks & sharing — team (join/adopt/connect), stacks (list/search/show/install), vault, marketplace.
• Setup, config & distribution — init, setup/unsetup, reconfigure, tour, config, bootstrap, validate, route, detect, reset, suggest, mcp, ci-check, export/import, version/upgrade, 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://jasgujral.github.io/mokata-oss/ (the published docs site; source in docs/, built with MkDocs)
• Changelog: CHANGELOG.md
• Issues & discussions: the repository's Issues / Discussions tabs