MasterMind

🌐 mastermind.mehrad.me

_{⚗️ Experimental (v0.27.0). Under active development — not yet stable, but usable. Its effect is measured in the open (see evals/RESULTS.md); APIs and defaults may change.}

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/_template/         # FIELD SCAFFOLD — init builds your field from this
    ├── stack-defaults · mentors · curriculum · learning-sources · lessons
    └── audit-rules.md        # framework-specific defect checks (for code-reviewer)
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, and each project gets its own copy of the brain in <project>/.mastermind/ — its own field, lessons and stack, committed so your team shares it. It wires the current repo's .claude/ (Claude Code) plus AGENTS.md / .cursor/rules / GEMINI.md for the tools you have — active only there. Prefer one shared brain for every project instead? add --shared. Want it everywhere at once? --global. You install from ~/.mastermind; that clone is the source.

It's safe and self-healing — re-run anytime: it backs up a real CLAUDE.md, appends (never overwrites) an existing AGENTS.md, refreshes the engine while keeping your project's own lessons, and repairs any wiring. 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.

Each project gets its own brain (isolated by default)

A per-project install now copies the engine into <project>/.mastermind/ — its own field, its own lessons.md, its own stack defaults — and commits it, so a teammate cloning the repo gets the same brain. Nothing a lesson learned in one client repo can leak into another.

cd my-project && ~/.mastermind/install.sh            # isolated — its own brain
cd my-project && ~/.mastermind/install.sh --shared   # opt back into the single shared clone

--check tells you when an isolated project has drifted behind the clone. lab/ stays gitignored either way. Run it from anywhere in the repo — it installs at the git root, so a monorepo gets one brain, not one per subfolder.

Monorepos: a different field per app

When one repo holds apps on different stacks — or two React apps with different conventions — give each its own context. A routes.map in the project's brain maps path globs to contexts:

# .mastermind/routes.map
apps/web/**    web
apps/api/**     api
packages/**       shared

The installer compiles that into each app's own tool-native anchor — a nested CLAUDE.md / AGENTS.md and a glob-scoped .cursor/rules — so the tool loads the right context by file path, not the model guessing. Web's lessons never reach api; each app pulls only its own field + context, so it's isolated and uses fewer tokens. A missing context is created from a template using the default field; edit its field.md to point at another field once you've bootstrapped one. A project with no routes.map is single-field — nothing changes, the common case stays simple.

Cursor is per-project only. --global covers ~/.claude and ~/.codex; Cursor has no equivalent user-level rules directory we can write, so run install.sh inside each repo you want it in. Without that, Cursor has no MasterMind at all — and you end up typing "use MasterMind" on every prompt to do by hand what the rule should do for you.

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.
• No field pack ships — only the scaffold at engineering/fields/_template/. init builds the field for your project's real stack (a pack tuned to someone else's stack is worse than none). The template is routable and integrity-checked, so a freshly built pack works on day one.

Credits

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

License

MIT — see LICENSE.