MasterMind

🌐 mastermind.mehrad.me

_{⚗️ Experimental (v0.23.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/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.

Credits

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

License

MIT — see LICENSE.