Merlin - The Ultimate AI Brain for Claude Code and Codex

  ███╗   ███╗███████╗██████╗ ██╗     ██╗███╗   ██╗
  ████╗ ████║██╔════╝██╔══██╗██║     ██║████╗  ██║
  ██╔████╔██║█████╗  ██████╔╝██║     ██║██╔██╗ ██║
  ██║╚██╔╝██║██╔══╝  ██╔══██╗██║     ██║██║╚██╗██║
  ██║ ╚═╝ ██║███████╗██║  ██║███████╗██║██║ ╚████║
  ╚═╝     ╚═╝╚══════╝╚═╝  ╚═╝╚══════╝╚═╝╚═╝  ╚═══╝

Merlin curates the best of the Claude Code and Codex CLI ecosystem and wires it together — automated, opinionated, and kept in sync. We didn't invent context engineering, spec-driven workflows, or adversarial code review. We integrated them. One install, you get the patterns the community converged on, made discoverable through slash commands, specialist agents, lifecycle hooks, and an MCP-backed knowledge layer. This is the AI development system connecting Claude Code, Codex CLI, MCP, and the broader ecosystem into a coherent whole.

Standing on the shoulders of

Merlin would not exist without these projects. We adapted patterns, code, and ideas from each — and we credit them in NOTICE.md. The full machine-readable ledger is in upstreams.yaml.

| Upstream | What we credit | Link | |---|---|---| | GSD (Get Shit Done) | .planning/ schema, /merlin:quick, /merlin:health --repair, fresh-context execution model, multi-runtime adapter pattern | gsd-build/get-shit-done | | BMAD-METHOD | <critical_actions> agent hardening, adversarial reviewer, edge-case-hunter, party-review, /merlin:next, /merlin:readiness-gate, /merlin:course-correct, dialectic challenge | bmad-code-org/BMAD-METHOD | | Ralph Wiggum technique | Merlin Loop (autonomous iterate-on-failure pattern) | snwfdhmp/awesome-ralph | | Claude Code Best Practice (shanraisshan) | Curated index of Claude Code patterns we draw from | shanraisshan/claude-code-best-practice |

Full attribution and per-file provenance in NOTICE.md.

Note: The historical internal get-shit-done/ directory in this repo (deleted in commit bfe5d2c v3.0.0) was an unrelated Merlin sub-package, not lifted from external GSD.

Quick Install

npx create-merlin-brain

Runtime Support

• Claude Code: full Merlin install with workflows, agents, hooks, statusline, and shell integration
• Codex: Merlin MCP, AGENTS.md, Codex hooks, custom Codex agents, repo skills, and project .codex config
• OpenCode / Gemini CLI: Merlin MCP plus instruction-file integration

What You Get

Workflows (/merlin:* commands)

| Command | Description | |---------|-------------| | /merlin:help | See all available commands | | /merlin:map-codebase | Analyze and document your codebase | | /merlin:new-project | Initialize project planning | | /merlin:create-roadmap | Create implementation phases | | /merlin:plan-phase | Create detailed execution plans | | /merlin:execute-phase | Execute plans with parallel agents | | /merlin:verify-work | Validate built features |

Agents

• merlin-executor - Executes plans with atomic commits
• merlin-codebase-mapper - Analyzes and documents codebases
• merlin-verifier - Validates phase completion
• merlin-researcher - Conducts systematic research
• product-spec - Turns ideas into specs
• system-architect - Designs simple architecture
• implementation-dev - Implements features
• hardening-guard - Security and error handling
• dry-refactor - Keeps code DRY and organized
• tests-qa - Designs and implements tests
• docs-keeper - Maintains documentation

Merlin Sights (Optional Enhancement)

Merlin Sights provides instant codebase context across sessions. Get your API key at merlin.build.

With Sights: Instant context, cross-session memory, duplicate prevention Without Sights: Full workflows still work, uses file exploration

How It Works

┌──────────────────────────────────────────────────────────────┐
│                      MERLIN                                  │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  MERLIN SIGHTS (Optional)                              │ │
│  │  Instant context • Cross-session memory                │ │
│  │  Falls back to file exploration if unavailable         │ │
│  └────────────────────────────────────────────────────────┘ │
│                           ↓                                  │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  MERLIN WORKFLOWS                                      │ │
│  │  /merlin:map-codebase • /merlin:plan-phase • etc.      │ │
│  └────────────────────────────────────────────────────────┘ │
│                           ↓                                  │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  MERLIN AGENTS                                         │ │
│  │  Parallel execution • Wave-based • Checkpoints         │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Getting Started

1. Install Merlin:

   npx create-merlin-brain

2. Open Claude Code or Codex in any project

3. Run your first command:

   /merlin:map-codebase

4. Start planning:

   /merlin:new-project

Codex Experience

On Codex, Merlin now installs beyond basic MCP connectivity:

• Global ~/.codex/config.toml MCP wiring for Merlin
• Global ~/.codex/hooks.json for startup, prompt routing, command guardrails, and session wrap-up
• Project .codex/agents/ with Merlin specialist agents
• Project .agents/skills/ with Merlin workflow skills
• Project AGENTS.md and .codex/config.toml for repo-local guidance
• Merlin capability discovery via merlin_help
• Automatic steering toward merlin_smart_route, merlin_recommend_for_task, and merlin_find_skill when Codex sees feature, bug, or resume-style prompts

Codex does not currently expose a documented extension point for replacing app-shell chrome or adding a custom sidebar icon, so Merlin parity is implemented on the supported surfaces Codex actually provides.

Typical Codex prompts:

Use Merlin to map this codebase before changing anything.

Use Merlin to find the best skill, agent, and workflow for this task: add OAuth login.

Call merlin_help for this task: debug the failing Stripe webhook tests.

Duo Mode (parallel + sequential dual-brain)

Run Claude and Codex on the same task: parallel for planning/docs/review/tests, sequential for code writing.

# Toggle in any Claude Code session:
"duo on"     # enable
"duo off"    # disable
"duo status" # check

When enabled, the badge swaps to ⟡🔮↔🔮 MERLIN·DUO › so you always know which mode you're in. Set MERLIN_BADGE_TEXTONLY=1 for emoji-hostile terminals.

Auto-offer: When duo is OFF and a task scores >=50 on the risk heuristic (auth, payments, migrations, etc.), Merlin asks if you want to enable duo for that task. Suppress with "skip session" or "never for X". 7-day expiry on intent suppressions.

Requires: Codex CLI installed. If not installed, Merlin silently uses solo mode.

Full rules: ~/.claude/rules/duo-routing.md.

Standalone Codex Users

If you run Codex directly (without Claude Code), use merlin-codex as a drop-in wrapper to get the Merlin orchestrator persona on every invocation:

merlin-codex                        # opens interactive Codex shell with Merlin banner
merlin-codex exec "add auth login"  # exec with Merlin system prompt prepended
merlin-codex "fix the failing test" # prompt mode with Merlin prompt prepended
merlin-codex login                  # pass-through — no prompt injection

The wrapper prints the Merlin banner to stderr, loads ~/.claude/merlin-system-prompt.txt (falls back to a one-liner if missing), and forwards all management subcommands (login, logout, mcp, etc.) unchanged.

Recommended reading

The single best curated index of Claude Code patterns we draw from:

• shanraisshan/claude-code-best-practice — 49k★ — community-curated catalog of 82 tips, 10+ workflow taxonomies, and expert distillations from Boris Cherny, Anthropic staff, and the broader community. Endorsed by the Claude Code creator. If you want to understand the patterns Merlin automates, start here.

Documentation

Visit merlin.build/docs for full documentation.

License

MIT