Repository context and evidence-backed workflows for coding agents.
Mastermind gives coding agents local code and documentation search, project knowledge, optional personal preferences, and a controller that checks task evidence before completion.
Requires Node.js 24+. The npm manifest lists prebuilt binaries for macOS, Linux, and Windows. Run these commands inside your repository:
npm install -g @xcraftmind/mastermind
mastermind initThe first interactive run asks for a client and mining mode. It creates project
guidance, indexes code and documentation, and configures the selected client.
An unattended first run stays local unless you pass --client.
| Command | Result |
|---|---|
mastermind init |
Apply saved project choices from .mastermind/setup.json |
mastermind status --json |
Inspect the index, client configuration, session observations, and miner |
mastermind update |
Update the package in its existing npm scope and refresh installed workflows |
mastermind ui --since main |
Open the read-only Lens UI against your chosen Git baseline |
Restart the selected client to load its configuration. Registration, session
observations, and client trust are separate states. Keep .mastermind/ working
data out of version control. See Getting started for
mining choices, Windows support, and other installation paths.
| Need | Result |
|---|---|
| Review a change | Changed symbols, callers, boundaries, and candidate tests |
| Find context | Code search, cited Markdown, decisions, and task history |
| Apply working preferences | Reviewed habits selected by project, role, and workflow |
| Delegate a task | Approved scope, observed checks, audit, and semantic review |
| Share evidence | Lens, offline HTML, SARIF, and audit envelopes |
| Import analysis | SCIP, scanner reports, coverage, tests, traces, and facts |
init --client claude|codex|all connects Claude Code, Codex, or both.
On first setup, a selected client defaults to local evidence capture.
Other clients use MCP setup.
| Context | Scope |
|---|---|
| Person | Advisory habits and preferences shared across repositories |
| Project | Repository decisions, constraints, and knowledge |
| Code and documentation | Indexed structure and cited source material |
| Role | Duties for this invocation |
| Workflow | Planning, execution, verification, and review |
| Task evidence | Results, blockers, and the reviewed revision |
Capture and personal-profile access are separate. --profile-access on opts
the selected project and clients into reading reviewed preferences. Those
preferences grant no action permissions. Context previews expose revisions
and omissions, not proof of model use. See Architecture
and Persona hooks.
mastermind new-spec "Add account recovery"Fill the goal, scope, acceptance criteria, and checks, then follow the Workflow guide:
criteria → implementation → checks → audit → review → complete or feedback
Any client can implement the spec. Recorded native execution and review use Claude Code. Completion requires current evidence and resolved review.
| Boundary | Meaning |
|---|---|
| Static codegraph | Dynamic dispatch, reflection, generated code, and cross-language calls may be incomplete |
| Personal profile | Reviewed preferences remain advisory |
| Task records | Local evidence does not independently establish correctness |
| Native process policy | Uses client restrictions, not an OS sandbox |
| Provider access | Indexing, deterministic queries, and Lens are local. Semantic mining, prompt refinement, drafting, execution, and review require explicit opt-in and can send content to a provider |
| Miner budgets | Repeated init preserves each run's counters, including stopped or exhausted runs. miner start explicitly starts a new run |
| Prompt refiner | Optional --refiner on uses additional calls outside the miner's call budget |
Language coverage includes Python,
TypeScript/TSX, JavaScript/JSX, Vue SFC, Rust, C#, Go, Java, PHP, and C/C++.
Native hooks, managed mining, and supervised execution require macOS or Linux.
Windows can use local indexing and client setup with --mining off. See
runtime support.
| Start | Reference |
|---|---|
| Getting started | CLI and MCP |
| Architecture | Benchmarks |
| Workflow | Changelog |
| All guides | Security policy |
Source builds require Rust 1.96+, declared in Cargo.toml.
cargo install --path mcp/servers/mmcg --locked
just checkCargo installs mmcg. npm exposes mastermind and mmcg.
See Contributing, GitHub Issues,
and the security reporting policy.
MIT.