Mastermind

A local codegraph and verifiable workflow for AI coding agents.

Mastermind gives Claude Code, Codex, Cursor, and Continue a structural view of your code: what exists, who calls it, what a change can affect, and which tests are relevant. Its optional workflow checks an agent's plan and implementation against the real repository instead of trusting the agent's memory.

What you get

The codegraph and deterministic style miner stay on your machine in local SQLite databases. Agent-assisted modes are explicit: init without --no-claude may send repository content through the configured Claude CLI, while miner profile --deep sends bounded samples for synthesis.

Try it in two minutes

Requires Node.js 24+. Prebuilt binaries are included; Rust is not required.

1. Install once

npm install -g @xcraftmind/mastermind

Connect the client you use:

mastermind install --client all                # Claude + Codex workflow adapters and MCP
mastermind setup cursor --scope user --write   # Cursor MCP
mastermind setup continue --scope user --write # Continue MCP

Use mastermind install for Claude only or mastermind install --client codex for Codex only. mastermind doctor --workflow --client all verifies that the ownership manifests, artifact lists, and SHA-256 content match the current package.

Global installation and MCP registration do not require a project or mastermind init. Setup is dry-run-first when --write is omitted.

2. Use it in a repository

cd your-project
mastermind index .
mastermind map .
mastermind impact --since main

index is enough for codegraph, map, and impact features. Run mastermind init only when you want the complete spec-driven project workflow:

mastermind init
mastermind doctor

See Getting started for global vs per-repository state, project-local installation, and client-specific setup.

Core workflows

Map a project

mastermind map .                     # readable architecture briefing
mastermind map src --format mermaid  # scoped diagram
mastermind map . --format json       # stable schema for automation
mastermind map . --production-only   # hide tests, fixtures, examples, generated/vendor code

The map highlights languages, components, entry points, dependency boundaries, hotspots, and cycles without asking an agent to grep the entire repository.

Understand change and test impact

mastermind impact --since main
mastermind impact --since HEAD~1 --format json

Impact analysis compares a Git baseline with committed, staged, unstaged, and untracked work. It reports symbol-level changes, affected callers, component crossings, and candidate tests. Focused candidates are evidence for prioritization, not a replacement for the repository's required test suite.

Review architecture invariants

Use /mastermind-architecture-review for changes that cross service, queue, state, retry, migration, or public-contract boundaries. It reconstructs the real runtime path and tests source-of-truth ownership, idempotency, and backward compatibility against concrete failure sequences.

Ask why the project works this way

mastermind history "webhook dedupe"
mastermind why "why is webhook dedupe durable?"

History searches active and archived CONTEXT files, canonical task specs, executor reports, audits, .mastermind/releases/, and reviewed lessons. A candidate lesson is only an audit signal until semantic review. The index is only a retrieval layer: Markdown remains authoritative, and the answer separates observed records from inference and missing proof.

Carry personal style across repositories

mastermind miner profile .

The deterministic miner writes a user-global ~/.mastermind/style.md and style.db; it works without mastermind init. Planner and executor treat the profile as advisory. Repository code, formatter/linter policy, the approved contract, product behavior, and security always win. Corpus-level code-shape observations are diagnostic rather than coding instructions; /mastermind-style-deep adds a qualitative, evidence-backed portrait that normal re-mining preserves.

Query the graph from an agent

The MCP server exposes 24 bounded tools for symbol search, callers/callees, imports, architecture maps, change impact, test impact, cycles, API surface, and project history. The same engine is available through the CLI.

"Does parseConfig exist?"
"Who calls createSession?"
"What could this branch affect?"
"Which tests are connected to these changes?"

See the mmcg reference for the complete tool and protocol contract.

Use only the workflow depth you need

Small changes stay direct: query the graph, implement, and run the repository checks. Normal delegated work uses a compact verified contract. Auth, migrations, public APIs, data-loss, and supply-chain changes use strict review.

flowchart LR
  U["Request"] --> M{"Risk"}
  M -->|small| D["Direct: impact + tests"]
  M -->|normal| P["Verified spec"]
  M -->|high| S["Strict spec + review"]
  P --> V["Verify"]
  S --> V
  V --> E["Implement"]
  E --> A["Audit the real diff"]
  D --> R["Report evidence"]
  A --> R

Direct mode needs only mastermind index .; no init or task spec is required. Verified and strict tasks keep planner, executor, and controller ownership separate, and post-flight requires a canonical executor report. Read How the workflow works for the exact modes and task lifecycle.

Produce verifiable audit evidence

Mastermind can seal audit results with SHA-256 integrity and detached Ed25519 signatures. The included GitHub Action verifies repository, baseline, head, worktree, signature, and policy inputs before evidence is published.

See Verifiable audits and GitHub Action.

What is global and what is per project?

Support

• Clients: Claude Code, Codex, Cursor, Continue, and generic MCP stdio clients
• Languages: Python, TypeScript/TSX, JavaScript/JSX, Rust, C#, Go, Java, PHP, and C/C++
• Platforms: macOS arm64/x64, Linux glibc and musl arm64/x64, Windows x64
• Privacy: deterministic parsing and storage are local; explicit agent-assisted modes disclose when repository samples are sent to the configured AI client

The graph is syntactic rather than compiler-semantic. Dynamic dispatch, reflection, re-exports, overload resolution, and cross-language calls can reduce precision. Mastermind reports bounded results and precision notes instead of presenting incomplete analysis as certain.

Documentation

• Getting started
• Claude Code · Codex · Cursor · Continue · Generic MCP
• Workflow
• mmcg technical reference
• GitHub Action and audit security model
• Changelog

Build from source

Rust 1.96+ is required for source builds:

cargo install mmcg
# or from a clone
cargo install --path mcp/servers/mmcg

The cargo-installed command is mmcg; the npm package exposes the same binary as both mastermind and mmcg.

Contributing

See CONTRIBUTING.md for the project layout, checks, evals, and pull-request conventions.

License

MIT — see LICENSE.