Mastermind

Make your AI coding assistant trustworthy. MasterMind is plain Markdown that gives Claude Code, Cursor and Codex 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 service to run and no package dependencies, just text that loads into your AI (installing it and running its CLI need Bash, Git and Node 18+). 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 supports Claude Code, Cursor and Codex, nothing else.

🗺️ 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.

Together they are the trust layer: 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.)
• No service to run, and no package dependencies. The knowledge is plain Markdown in git: greppable, diffable, reviewable. The moving parts are the ones you already have: Bash and Git to install, Node 18+ for the installer, the generated scripts and the mastermind CLI, whose npm package itself declares no dependencies.

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, Cursor, or Codex. 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
npx mastermind-brain

# Prefer it everywhere? one global install for all projects:
npx mastermind-brain --global

Every npm release is a versioned, immutable, provenance-signed artifact, and a fresh install pins the brain to the matching git tag: you always know exactly what ran, and you can read all of it first (npm pack mastermind-brain: the whole CLI is ~10 KB packed, 26 KB unpacked, on top of this repo).

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, ready to commit so your team shares it (the installer never commits for you: review the diff, then git add .mastermind .claude .cursor AGENTS.md). It wires the current repo's .claude/ (Claude Code) plus AGENTS.md / .cursor/rules 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. It makes exactly one edit to your settings: it merges the MasterMind SessionStart hook entry into .claude/settings.json, leaving every other key exactly as it was (and leaving the file alone entirely if it cannot be parsed). uninstall removes just that entry. Your sessions and memory are never touched or published.

npx mastermind-brain update      # refresh the brain + repair links
npx mastermind-brain check       # is this project wired?
npx mastermind-brain 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: npx mastermind-brain uninstall --global, then run npx mastermind-brain 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 npx mastermind-brain too: the plugin adds the command surface, the installer wires the brain.

Per tool (what a per-project install wires)

Those three are what MasterMind supports. The brain is plain Markdown with no tool-specific mechanisms inside, so another tool that reads an instruction file may well load it: but we don't wire it, test it, or claim it works, and the installer will tell you so rather than half-wiring something.

With --global, Claude Code is 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 && npx mastermind-brain                 # isolated: its own brain
cd my-project && npx mastermind-brain --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 for Codex); Cursor has no equivalent user-level rules directory we can write, so run npx mastermind-brain 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), quarantine (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.

Checking on it

You never need these. MasterMind calls them itself, which is the point: in Cursor and Codex, which have no native skill mechanism, it can ask for the one skill it needs instead of pasting the whole library into context. They are read-only, so nothing installs or changes when you run them.

mastermind skills                      # the routing table: every skill, one line each
mastermind skill performance           # the instructions it actually follows
mastermind route "why is this slow?"   # the table again, with keyword matches arrowed
mastermind conflicts                   # what else is installed, and where it overlaps
mastermind wrong-log                   # every time it got something wrong, and what caught it

Add --json to parse any of them. Without a global npm install, call the copy in your project: .mastermind/bin/mastermind skills.

When you have other skill packs installed: and most people will, precedence is: your project's own skills → installed packs → MasterMind's defaults. Where two disagree about a rule (committing, running tests, scope), the stricter one wins. mastermind conflicts shows the overlaps; measured routing barely moves in a crowded install, so it reports rather than resolves.

wrong-log is the honest answer to "can I trust this?": a record of misses with the thing that caught each one named, not a self-assessment. Empty means nothing was logged, not that nothing went wrong.

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 lands as an edit to a Markdown file in your working tree, so you read the diff and decide whether to commit it: nothing is committed for you, and git checkout throws away anything you don't want.

Private by default

Sensitive project data (a client's stack, a team's internal patterns) stays in a gitignored lab/, behind pre-commit and pre-push hooks that scan for lab/ paths, denylisted names and credential patterns and refuse the operation when they find one. Only the generic, name-free lesson ever graduates into the shareable knowledge base: patterns, not identities.

These are git hooks, so they are a strong default rather than a guarantee: they only run once installed (core.hooksPath set), --no-verify and ALLOW_SENSITIVE=1 skip them on purpose, and nothing stops a file being copied out of lab/ by hand. They are there to make an accidental leak fail loudly, not to make one impossible.

Where it's tested

MasterMind is plain Markdown with no runtime. It is developed and measured on Claude Code: that's where the numbers in evals/RESULTS.md come from: and it is exercised on Cursor, where the kernel and the active field pack are injected as always-on rules. Neither tool has its own mechanisms broken by it.

The installer wires those two plus AGENTS.md. Everywhere else the brain still loads. It's just files: but whether it changes that tool's output is not something we've measured, so it isn't something we claim. If you try it and can measure a difference either way, that's the most useful contribution you could make.

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.