Complete Reference

Everything Merlin does.

Every agent, command, hook, and tool — what it does, why it matters, and how to use it.

34agents
43commands
20hooks
12tools
4workflows
01

Specialist Agents

34 agents. Every task, a specialist.

Core Pipeline

product-specagent

Your ideas become buildable specs with requirements, user flows, and edge cases — in minutes, not days.

/merlin:route product-spec "task"
system-architectagent

Designs clean architecture that prevents the spaghetti code AI usually creates. Checks for conflicts before building.

/merlin:route system-architect "task"
implementation-devagent

Writes production code that matches YOUR patterns, not generic boilerplate. Reuses existing utilities instead of creating duplicates.

/merlin:route implementation-dev "task"
dry-refactoragent

Finds the code duplication you missed. Consolidates utilities. Enforces the 400-line file limit that keeps code maintainable.

/merlin:route dry-refactor "task"
hardening-guardagent

The layer between "it works" and "it's production-ready." Adds validation, error handling, auth checks, and input sanitization.

/merlin:route hardening-guard "task"
tests-qaagent

Writes tests that actually matter — critical paths, edge cases, regression prevention. Not just coverage for coverage's sake.

/merlin:route tests-qa "task"
ops-railwayagent

Handles deployment configs, environment variables, and build pipelines so you never debug a deploy again.

/merlin:route ops-railway "task"
docs-keeperagent

Documentation that stays current because it's generated from the code, not maintained separately.

/merlin:route docs-keeper "task"

Specialists

ui-designer

Component architecture and design systems that scale. Not just pixels — structure.

agent
ui-builder

Frontend implementation that's responsive, accessible, and follows your component patterns.

agent
animation-expert

60fps animations that feel right. Transitions, micro-interactions, scroll effects.

agent
apple-swift-expert

Swift 6, SwiftUI, AppKit. Full iOS/macOS lifecycle — from architecture to App Store submission.

agent
android-expert

Kotlin, Jetpack Compose, Material Design 3. Full Android lifecycle.

agent
desktop-app-expert

Electron, Tauri, cross-platform distribution. IPC security included.

agent
merlin-debugger

Scientific-method debugging with persistent state across context resets. Manages checkpoints so no context is lost.

agent
merlin-performance

Finds the bottleneck, not just the slow code. Profiling with benchmarking guidance.

agent
merlin-security

Deep security audits with OWASP awareness. Thinks like an attacker so your app doesn't get treated like one.

agent
merlin-reviewer

Code review that catches architectural issues, not just style nits.

agent
merlin-frontend

React, Vue, modern web. State management, accessibility, performance — all applied together.

agent
merlin-api-designer

Clean REST and GraphQL APIs with versioning, error handling, and documentation baked in.

agent
merlin-migrator

Database migrations that won't take your app down. Rollback strategies. Zero-downtime.

agent
merlin-planner

Creates execution plans with dependency graphs and wave-based parallelization. Spawns a fresh planning context.

agent
merlin-executor

Executes plans with atomic commits and deviation handling. Stops if something goes wrong.

agent
merlin-verifier

Verifies that what was built actually delivers what was promised. Goal-backward analysis.

agent
merlin-researcher

Deep research with source verification before you make architecture decisions. Know before you build.

agent
elite-code-refactorer

Transforms code into production-grade quality. Memory leak detection, race conditions, line-by-line review.

agent
code-organization-supervisor

Monitors file sizes, enforces folder structure. Catches files before they become unmaintainable.

agent
context-guardian

Scans the codebase before you write new code to prevent duplicating existing functionality.

agent
remotion

Creates programmatic videos using React. Compositions, animations, rendering, deployment.

agent
merlin-sast-reviewer

Catches injection flaws, XSS, SSRF before they reach production. Static analysis with context.

agent
merlin-dependency-auditor

Finds CVEs in your dependencies, supply chain risks, and license compliance issues.

agent
merlin-secret-scanner

Detects hardcoded credentials and API keys before they get committed. Pre-commit protection.

agent
merlin-access-control-reviewer

Reviews auth flows, CSRF protection, rate limiting. The stuff that gets breached.

agent
merlin-input-validator

Ensures every endpoint validates its inputs. No unvalidated data ever reaches your business logic.

agent
02

Slash Commands

43 commands. Every workflow, covered.

Project Setup

/merlin:new-project

Deep context gathering that creates a PROJECT.md your AI actually understands. No more re-explaining your app every session.

command
/merlin:create-roadmap

Turns requirements into phased roadmaps with dependencies and execution waves. Structured delivery, not chaos.

command
/merlin:define-requirements

Defines what "done" looks like with checkable requirements. Prevents scope creep before it starts.

command
/merlin:new-milestone

Start a new milestone cycle with an updated PROJECT.md. Clean slate, preserved history.

command
/merlin:map-codebase

Parallel mapper agents analyze your codebase and write structured documents to .planning/codebase/. Full knowledge, instantly.

command

Planning

/merlin:plan-phase

Creates PLAN.md files with dependency graphs and wave parallelization. Spawns a fresh planner with 200K context.

command
/merlin:discuss-phase

Adaptive questioning before planning. Surfaces unknowns before they become blockers.

command
/merlin:discuss-milestone

Gathers context for the next milestone through conversation. Aligns before committing.

command
/merlin:research-phase

Research how to implement a phase before committing to a plan. Saves expensive mistakes.

command
/merlin:research-project

Research the domain ecosystem before creating a roadmap. Know the landscape before building in it.

command
/merlin:list-phase-assumptions

Surfaces Claude's assumptions about a phase so you can correct them before planning starts.

command
/merlin:readiness-gate

Validates planning is complete before implementation begins. Catches gaps that would stall execution.

command
/merlin:add-phase

Add a new phase to the end of the current milestone without disrupting existing numbering.

command
/merlin:insert-phase

Insert urgent work as a decimal phase (e.g., 72.1) between existing phases without renumbering everything.

command
/merlin:remove-phase

Remove a future phase and automatically renumber all subsequent phases.

command

Execution

/merlin:execute-phase

Executes all plans in a phase with wave-based parallelization. Multiple agents run in parallel, each in a fresh 200K context.

command
/merlin:execute-plan

Execute a single PLAN.md file step by step with full atomic commit tracking.

command
/merlin:route

Route any task to the right specialist agent with a fresh 200K context window. The most-used command in Merlin.

command
/merlin:quick

Run an ad-hoc task with Merlin guarantees but no ceremony. No plan files, no phase tracking. Just execute.

command
/merlin:workflow

Run predefined multi-agent pipelines: feature-dev, bug-fix, security-audit, refactor. End-to-end, structured.

command

Verification

/merlin:verify-work

Validates built features through conversational UAT with persistent state. Cold reviewer confirms delivery.

command
/merlin:audit-milestone

Audits milestone completion against original intent. Did you actually deliver what was promised?

command
/merlin:complete-milestone

Archives the completed milestone and prepares PROJECT.md for the next version. Clean transition.

command
/merlin:plan-milestone-gaps

Creates phases to close all gaps identified by the milestone audit. Nothing left behind.

command

Navigation

/merlin:next

Smart navigator — detects project state and recommends the single best next action. Never wonder "what now?"

command
/merlin:progress

Check project progress, show current context, and route to the next action.

command
/merlin:standup

Generate daily standup summary — done, in progress, blocked. Copy-paste ready for Slack.

command
/merlin:health

10-point planning integrity check. --repair auto-fixes common issues before they stop execution.

command
/merlin:check-todos

List all pending todos and select one to work on. Keeps tasks from disappearing into context.

command
/merlin:add-todo

Capture an idea or task as a todo from the current conversation context. Nothing gets lost.

command

Session Management

/merlin:resume-work

Resume work from a previous session with full context restoration. Pick up exactly where you left off.

command
/merlin:pause-work

Create a structured context handoff when pausing work mid-phase. Future sessions start informed, not blank.

command
/merlin:course-correct

Handle plan pivots — when implementation reveals the plan needs changing. Structured deviation, not chaos.

command
/merlin:debug

Systematic debugging with persistent state across context resets. Scientific method applied to every bug.

command

Advanced

/merlin:profiles

Snapshot and switch between agent/hook/rule configurations. Dev profile, review profile, release profile.

command
/merlin:sandbox

Isolated Docker execution for agents. Build, run, shell, status — resource-limited and clean.

command
/merlin:promote

Promote a high-confidence learned behavior into a permanent reusable skill. Merlin learns what works.

command
/merlin:optimize-prompts

Analyze agent prompt effectiveness with RL-inspired scoring. Surface which prompts deliver results.

command
/merlin:usage

Session cost report — per-agent breakdown, token counts, savings vs all-Opus baseline. Know your spend.

command
/merlin:update

Update Merlin to the latest version with changelog display. Stay current with one command.

command
/merlin:whats-new

See exactly what changed since your installed version. No guessing what's different.

command
/merlin:help

Show available Merlin commands and usage guide. Always available, always accurate.

command
/merlin:loop-recipes

Pre-built /loop patterns for common Merlin workflows. Copy-paste ready automation.

command
03

Automated Hooks

They run without you. That's the point.

security-scanner

Scans every file write, edit, and bash command for prompt injection patterns, hardcoded secrets, and data exfiltration. 21 injection patterns checked.

automatic
smart-approve

Auto-approves 45+ safe commands (git status, npm test, ls) and blocks dangerous ones (rm -rf, curl to external). No permission fatigue.

automatic
check-file-size

Enforces the 400-line file limit. Stops files from becoming unmaintainable before it happens — not after.

automatic
pre-edit-sights-check

Checks Sights for context before every file modification. Your AI always knows what it's editing, not just what you told it.

automatic
instructions-loaded

Pre-warms Sights context at session start. Your AI has full codebase knowledge from the first prompt, not after you explain the project.

automatic
session-end

Generates a structured session summary, classifies outcomes, and appends to the learning engine. Every session makes Merlin smarter.

automatic
session-end-memory-sync

Syncs architectural decisions to Sights API asynchronously. Future sessions start with your decisions already in context.

automatic
notify-desktop

Desktop notification when agents complete. macOS and Linux. Never miss a result while you context-switch.

automatic
notify-webhook

Slack and Discord webhook notifications on agent completion. Fire-and-forget delivery to your team.

automatic
worktree-create

Propagates .merlin-session/ state to isolated worktrees. Agents in worktrees get full context — not a blank slate.

automatic
worktree-remove

Logs lifetime analytics and cleans up .merlin-session/ state when a worktree is removed. No orphaned state.

automatic
config-change

API key validation and audit trail to config-changes.log on every configuration modification. Catches misconfigurations before they cause silent failures.

automatic
teammate-idle-verify

Detects when a teammate agent has been idle for 2+ minutes. Creates alert files for the Lead so parallel work stays unblocked.

automatic
04

Hook Templates

10 opt-in automations. Enable what fits your workflow.

auto-format

Auto-formats code on every save. Prettier and ESLint integration. Consistent style without thinking about it.

opt-in
auto-test

Runs affected tests after every code change. Catches regressions immediately, not at PR review.

opt-in
auto-commit

Auto-commits after successful changes with descriptive messages. Keeps history clean and granular.

opt-in
branch-protection

Prevents direct commits to main/master. Forces the branch workflow that protects production.

opt-in
complexity-check

Warns when cyclomatic complexity exceeds thresholds. Keeps code simple enough to understand and test.

opt-in
changelog-reminder

Prompts for changelog entries on significant changes. Significant features never go undocumented again.

opt-in
import-audit

Validates imports match project conventions. Catches wrong import paths before the build does.

opt-in
license-header

Ensures license headers appear on new files. Compliance automation that costs you nothing.

opt-in
todo-tracker

Tracks TODO comments and surfaces them as actionable tasks. Nothing promising gets lost in the codebase.

opt-in
pr-description

Auto-generates PR descriptions from commit history. Better pull requests with zero extra effort.

opt-in
05

MCP Tools

12 tools the AI calls automatically — you never invoke these directly.

merlin_get_context

Gives your AI instant understanding of how any part of your codebase works — conventions, patterns, anti-patterns. Called before every file edit.

tool
merlin_search

Semantic search across your codebase. Find code by meaning, not by filename or exact string match.

tool
merlin_find_files

Finds relevant files for a given task. Faster than grep, smarter than glob — context-aware file discovery.

tool
merlin_route

Routes tasks to specialist agents with effort-level optimization. High-effort tasks get more compute; quick tasks run lean.

tool
merlin_session_cost

Tracks per-agent cost, token counts, and savings vs all-Opus baseline. Know exactly what you're spending on every task.

tool
merlin_prompt_suggestions

RL-inspired prompt effectiveness scoring. Surfaces which agent prompts produce the best results over time.

tool
merlin_promote_behavior

Promotes learned behaviors into permanent skills using Jaccard keyword clustering. Merlin learns from every session.

tool
merlin_list_promotion_candidates

Lists behaviors ready for promotion based on confidence scores. Shows you what Merlin has learned and is ready to formalize.

tool
merlin_session_restore

Restores context from previous sessions. Structured summaries, not raw transcripts — fast and accurate.

tool
merlin_session_search

Keyword search across all session history. Find what was decided, discussed, or built in any past session.

tool
merlin_impact_analysis

Shows what breaks before you edit. Every dependent file surfaced instantly — before the change, not after.

tool
merlin_similar_code

Finds code similar to what you're about to write. Prevents duplication before it happens.

tool
06

Multi-Agent Workflows

4 end-to-end pipelines. Entire feature lifecycle in one command.

feature-devworkflow

7-step pipeline: spec → architecture → implement → harden → test → verify → PR. Each step runs in a fresh 200K context. A cold reviewer verifies at the end.

/merlin:workflow run feature-dev "description"
bug-fixworkflow

6-step pipeline: triage → investigate → fix → regression test → verify → PR. Finds root cause, not just symptoms.

/merlin:workflow run bug-fix "description"
security-auditworkflow

5-step pipeline: scan → prioritize → fix → independent review → security tests. OWASP-aware at every step.

/merlin:workflow run security-audit
refactorworkflow

5-step pipeline: analyze → plan → apply → verify behavior preservation → test. Safe, verified refactoring with no surprises.

/merlin:workflow run refactor "scope"
07

Runtime Support

Works where you work. Every major AI coding environment.

Claude Code

Full integration. All 34 agents, 43 commands, 20 hooks, Loop, everything included.

runtime
Codex CLI

Full integration. Same agents, hooks, and commands via MCP. Configured automatically.

runtime
OpenCode

Full integration. Same complete system. Drop-in installation.

runtime
Gemini CLI

Full integration. Same agents and tools via MCP server.

runtime
Cursor

MCP context integration. Sights queries and pattern enforcement for every edit.

runtime
Windsurf

MCP integration. Full codebase knowledge layer available in every session.

runtime
Any MCP tool

If it speaks MCP, Merlin works. The protocol is the integration layer.

runtime

One install. All of this.

$npx create-merlin-brain

Works with Claude Code, Codex CLI, OpenCode, Gemini CLI