Mastermind

Mastermind makes coding agents check their claims against your real code, not their memory.

It's two parts:

1. mmcg — a local codegraph. A fast Rust indexer turns your repo into a queryable graph of symbols, calls, and imports, served to the agent over MCP. Does parseConfig exist? Who calls it? What breaks if I change it? — answered from the index, not a guess.
2. A spec-driven agent workflow built on it. The planner writes a spec, the executor implements it, and deterministic gates verify every claim before and after — so no hallucinated functions and no silent scope creep reach your branch.

Quick start

Requires Node.js 24+. No Rust toolchain.

npm install -g @xcraftmind/mastermind
mastermind install                     # workflow agents + skills + MCP → Claude Code (global, once)

cd your-project
mastermind init                        # build the codegraph index for this repo
mastermind doctor                      # verify — should be all green

Restart Claude Code and ask "who calls parseConfig?" — the answer comes from the codegraph.

Other install methods ↓

mmcg — the codegraph

A Rust binary that tree-sitter-parses nine languages (Python, TypeScript/TSX, JavaScript/JSX, Rust, C#, Go, Java, PHP, C/C++) into a local SQLite database and answers structural questions over MCP — 20 read-only tools:

All 20: mmcg_search · mmcg_callers · mmcg_callees · mmcg_impact · mmcg_imports · mmcg_imported_by · mmcg_symbols_in_file · mmcg_outline · mmcg_files · mmcg_api_surface · mmcg_unreferenced · mmcg_dependency_cycles · mmcg_symbols_changed_since · mmcg_centrality · mmcg_change_class · mmcg_recent_changes · mmcg_tasks · mmcg_status · mmcg_scratchpad_append · mmcg_scratchpad_read. Precision notes: mcp/servers/mmcg/README.md. Works with any MCP stdio client (Cursor, Continue, custom), not just Claude Code.

It's intentionally narrow — a syntactic graph, read-only, no daemon, zero system dependencies. Point queries are sub-millisecond; whole-graph aggregations (centrality, impact, cycles) scale with repo size. Faster and more precise than grep for "who calls what," and unlike an LSP it's trivial to snapshot and query from an agent.

More than an MCP server. MCP is one surface; the same mastermind binary is the workflow's engine. The deterministic gates (verify-spec / audit-spec) read the index directly, init / doctor scaffold and health-check a project, and miners derive cross-repo signal the workflow can consume — e.g. miner profile learns your code-shape style ("write like me") into ~/.mastermind/style.md for the planner to write in.

The workflow

A pipeline where the planner never implements and the executor never improvises:

flowchart TB
  U([User]) --> Ref[Intake Refiner • Sonnet]
  Ref -->|clean brief| P[Planner • Opus]
  P -.->|stress-test design| C[Critic • Opus]
  P -.->|gather facts| R[Researcher • Haiku]
  P -.->|unknown-cause bug| I[Investigator • Sonnet]
  P -.->|security-sensitive scope| S[Security Auditor • Opus]
  P -->|spec| E[Executor • Sonnet]
  E -->|report| A[Auditor • Opus]
  A -.->|held / drift / broken| P
  M[(mmcg codegraph)]
  P --- M
  E --- M
  A --- M

The critic (before the spec) and auditor (after execution) run as independent Opus instances with no prior context — they catch the planner's own bias.

The gates make it deterministic

Every spec is checked by Rust gates that read the mmcg index directly — a verdict can't be argued out of them:

• verify-spec (pre-execution) — every symbol in the spec exists, every file is on disk, mandatory sections are filled, FIND blocks aren't stale.
• audit-spec (post-execution) — no scope creep, no signature drift vs the pre-edit snapshot, no silently removed symbols, planned tests actually added.

The subagents query mmcg too, but that's an LLM interpreting results — useful, not a guarantee. Trust the gates for correctness; trust the subagents' mmcg use for speed and reach.

Example: catching a hallucinated function

The executor reported:

[x] Added CancelOrder() to pkg/checkout/checkout.go
[x] Wired it to the existing ProcessPayment() for the refund flow
VERIFY: go test ./pkg/checkout/... — PASSED

The auditor ran mmcg_search ProcessPayment against the live index → { "count": 0 }. ProcessPayment never existed; the executor invented a call site to it. Verdict: contract broken — caught by the graph, not by re-reading code.

What's inside

Core
  mcp/servers/mmcg/     the mmcg core binary — codegraph (20 MCP tools, 9 languages),
                        deterministic CLI gates, and miners (author style profile)

Workflow (installed into ~/.claude/ by `mastermind init`)
  agents/subagents/     prompt-refiner · critic · researcher · investigator
                        task-executor · auditor · security-auditor
  agents/claude-md/     CLAUDE.md + CONTEXT.md templates
  skills/workflow/      task-planning · task-executor · codegraph-research
                        structured-report-contract · critical-review
  skills/debugging/     investigation-ledger
  skills/security/      agent-security-review (OWASP ASI reference pack)
  skills/prompt-engineering/  prompt-refiner (intake gate)
  skills/coding/        no-ai-slop-comments

Proof
  evals/                adversarial eval suites — critic · auditor (real git fixtures) · intake
                        + ablation study (vanilla vs mastermind catch-rate)

Shared contracts — codegraph queries, the executor↔auditor report format, the investigation loop — live in skills so every agent reads one source. Non-core artifacts (pr-review, flaky-finder, doc-stub-sync, …) live in extras/, not installed by default.

Install

Ships as a prebuilt native binary via npm — no Rust toolchain.

Global (recommended)

npm install -g @xcraftmind/mastermind
mastermind setup claude --write-mcp

Registers command: "mastermind" at Claude Code user scope (writes ~/.claude.json).

Project-local (version-pinned)

npm install -D @xcraftmind/mastermind
npx mastermind setup claude --project . --write-mcp

Writes ./.mcp.json pointing at ./node_modules/.bin/mastermind.

One-command setup — npx @xcraftmind/mastermind install copies the subagents + skills into ~/.claude/ and registers the mmcg MCP. Then run mastermind init in a project to build the codegraph index. list shows what ships; update refreshes the agents.

Supported platforms: macOS (arm64/x86_64), Linux glibc & musl/Alpine (x86_64/arm64), Windows (x86_64). Other targets: cargo install mmcg.

cargo install mmcg                       # from crates.io
cargo install --path mcp/servers/mmcg    # from a clone

Commands

mastermind install               # workflow agents + skills + MCP → Claude Code (global, once)
mastermind update / list         # refresh the workflow bundle · show what ships
mastermind init                  # scaffold .mastermind/, build the index, draft CONTEXT.md
mastermind watch                 # keep the index live as you edit
mastermind doctor                # fail-soft health checks (add --json for CI)
mastermind status / next         # task list + health · single next step
mastermind new-spec "..."        # create a task spec (--mode lite|standard|strict)
mastermind resume <task-id>      # paste-into-Claude prompt for the current phase
mastermind verify-spec <spec>    # pre-execution gate
mastermind audit-spec <spec>     # post-execution gate
mastermind miner profile         # learn your code-shape style → ~/.mastermind/style.md
mastermind uninstall --scope all # tear it down (dry-run unless --force)

Stays local. The SQLite index is built from your files by tree-sitter and never leaves your machine. install / init write the workflow bundle into ~/.claude/{agents,skills,commands}/ and setup registers the MCP server in ~/.claude.json — all local, no network beyond the npm registry. Fully offline: mastermind init --no-claude --no-index --no-global. Add .mastermind/ to .gitignore — it's local working state.

Contributing

See CONTRIBUTING.md — project layout, the checks to run, and how to open a PR.

License

MIT — see LICENSE.