Mastermind

Make your AI coding assistant trustworthy. MasterMind is plain Markdown that gives Claude Code, Codex, Cursor, Copilot, and any AGENTS.md tool sharp defaults, real engineering judgment, and the discipline to check its own work — so you can rely on what it produces instead of watching every edit.

No app, no dependencies — just text that loads into your AI. You don't learn any commands: you talk normally ("build me X", "why is this slow?", "review this") and MasterMind applies the right discipline automatically. It improves itself over time, and it's tool-agnostic — one brain for every editor.

🗺️ New here? Explore the live interactive map.

Why it exists

Your AI already knows JavaScript, React, and algorithms. Re-teaching those wastes tokens. MasterMind adds only what's missing — the judgment and rigor that turn "looks right" into "verified":

• Good defaults — which tool/pattern to reach for, so it picks the best option, not the average one.
• A way to decide — how to choose when there's no obvious default.
• A habit of checking — verify the work end-to-end before calling it done; never ship lazy code.
• Your team's real style — it can learn a codebase's actual conventions and follow them.
• Lessons from real use — it writes down what it learns and gets sharper.

This is the "trust layer" in Anthropic's own model of AI adoption: the self-verification that lets you stop supervising every change and start relying on the output.

What makes it fast & lean

• Loads only what your task needs — the router. MasterMind's knowledge is many small files. Instead of pulling in the whole pack to work out what's relevant, a prebuilt index (engineering/ROUTER.md, generated by scripts/build-router.mjs — no AI, no network) points each task straight to the one or two files it needs. The saving is every file it doesn't load: measured ~65% fewer tokens per task (measured; more on single-file tasks, less on multi-file ones). If the index is ever missing, it just loads the field the normal way — a pure speed-up, never a dependency.
• Tiny always-on core. An AI gets duller as its context fills, so the always-loaded kernel is small; depth lives in on-demand skills and field packs that load only when relevant. (This is the pattern Anthropic recommends for scaling — CLAUDE.md + lazily-loaded skills.)
• Nothing to run. Plain Markdown in git — greppable, diffable, reviewable.

Architecture: a lean kernel + on-demand modules

CLAUDE.md                     # the kernel — always loaded, tiny
engineering/
├── active-field.md           # which field is active + how leveling works
├── ROUTER.md                 # generated map: loads only the files a task needs
├── core/                     # UNIVERSAL — how to think & work (field-agnostic)
│   ├── mindset · principles · rigor · agent-loop · product-sense
└── fields/frontend/          # FIELD PACK — swap or add per domain
    ├── stack-defaults · mentors · curriculum · learning-sources · lessons
    ├── audit-rules.md        # framework-specific defect checks (for code-reviewer)
    ├── web-animations.md     # complete motion playbook
    └── ui-ux-pro-max/        # design-intelligence database
agents/                       # architect · code-reviewer · refactorer · tech-scout
skills/                       # auto-applied workflows (you never have to type these)
lab/                          # your private, gitignored space for sensitive project data

Install

First, you need an AI coding tool — MasterMind is the brain that plugs into one. If you don't have one yet, install Claude Code (or Codex, Cursor, Copilot, Gemini). Then, from inside the project you want it in:

# Per-project (default) — wires MasterMind into THIS project, for every AI tool you have:
cd my-project
curl -fsSL https://raw.githubusercontent.com/mehrad-dm/mastermind/master/bootstrap.sh | bash

# Prefer it everywhere? one global install for all projects:
curl -fsSL https://raw.githubusercontent.com/mehrad-dm/mastermind/master/bootstrap.sh | bash -s -- --global

MasterMind installs per project by default: it wires the current repo's .claude/ (Claude Code) plus AGENTS.md / .cursor/rules / GEMINI.md for the other tools you have — active only there. Run it in each project you want it in, or use --global once for all. The clone lives at ~/.mastermind — the single source of truth every project links to.

It's safe and self-healing — re-run anytime: it backs up a real CLAUDE.md, appends (never overwrites) an existing AGENTS.md, and prunes stale links + relinks current skills/agents. Nothing personal (sessions/memory/settings) is touched or published.

cd ~/.mastermind && git pull && ~/.mastermind/install.sh   # update the brain + repair links
~/.mastermind/install.sh --check                           # is this project wired?
~/.mastermind/install.sh --uninstall                       # remove from this project (or --global)

Restart your tool after installing — until you do, the brain isn't loaded. Then confirm it's live: ask "are you running as MasterMind?"

Already installed globally (pre-0.20)? Your setup keeps working — nothing breaks. To switch to per-project: ~/.mastermind/install.sh --global --uninstall, then run ~/.mastermind/install.sh inside each project you want.

Or add it as a Claude Code plugin

/plugin marketplace add mehrad-dm/mastermind
/plugin install mastermind@mastermind

This registers the skills and agents as native commands (user-global). They read the brain from ~/.mastermind, so run install.sh too — the plugin adds the command surface, install.sh wires the brain.

Per tool (what a per-project install wires)

With --global, Claude Code + Codex are wired once in ~/ for every project instead.

Just talk — no commands to learn

You never have to invoke anything. Describe what you want; MasterMind recognizes it and applies the matching skill. (Power users can type /name as a shortcut, but nobody has to.)

Also auto-applied (and callable by name): explain (AI-friendly docs for an internal package), lab (a private, gitignored space for sensitive data), handoff, and levelup (teach MasterMind something durable). Specialist agents — architect, code-reviewer, refactorer, tech-scout — handle deep, isolated-context work. Full index: skills/README.md.

How it levels up

An LLM's weights are fixed; MasterMind improves by editing its own knowledge base. It turns your corrections and review findings into durable lessons, refreshes best-practices against the live ecosystem, and can bootstrap a whole new field pack for your stack. Every improvement is a git commit — visible and reversible.

Private by default

Sensitive project data (a client's stack, a team's internal patterns) stays in a gitignored lab/ and is protected by commit/push guards, so it can never be published by accident. Only the generic, name-free lesson ever graduates into the shareable knowledge base — patterns, not identities.

Model-agnostic by design

Plain Markdown, no runtime — works with any model (Claude, GPT/Codex, Gemini, local) and any tool. Claude Code gets native agents and skills; other tools read the same files and follow them as procedures. One brain, every editor.

Known limitations

Stated plainly, because a tool about not overclaiming shouldn't overclaim about itself.

• The numbers are a self-administered eval, not a benchmark. 8 tasks, N=3, three independent judges, same base model on both sides. Trust the delta (both sides judged identically); treat absolutes as directional. Method and full results: evals/. Mechanism runs that don't clear that bar are marked in evals/RESULTS.md and are never quoted publicly.
• Cursor re-injection is unverified. The .cursor/rules/mastermind.mdc rule works and is the load-bearing path. The sessionStart/preCompact hook is wired to Cursor's published schema, but Cursor has open upstream bug reports where a hook's additional_context is accepted and never reaches the model — so we wire it and say so, rather than claim it works. The installer prints (unverified upstream) when it wires it.
• Only one field pack ships (frontend). The template is now routable and integrity-checked, so a new pack works on day one — but nobody has built a second one yet.

Credits

Created and maintained by mehrad-dm. Built with Claude Code (Anthropic).

License

MIT — see LICENSE.