create-merlin-brain 3.11.0 → 3.13.0

package/files/commands/merlin/route.md

@@ -34,12 +34,14 @@ Both modes spawn a fresh process. The difference is whether the orchestrator gat
 Extract from $ARGUMENTS:
 - **agent-name**: First word (e.g., `product-spec`, `implementation-dev`)
 - **task-description**: Everything after the first word (may be quoted)
+- **--sandbox**: Optional flag — if present, run the agent inside the Docker sandbox
 
 If no arguments provided:
 ```
-Usage: /merlin:route <agent-name> "task description"
+Usage: /merlin:route <agent-name> "task description" [--sandbox]
 
 Example: /merlin:route product-spec "turn this into a spec: user wants SSO login"
+Example: /merlin:route implementation-dev "refactor auth module" --sandbox
 ```
 List available agents and exit.
 
@@ -173,6 +175,8 @@ Also write a detailed result to: {RESULT_FILE}
 
 This is the critical step. ALWAYS use `claude --agent` via Bash for true process isolation.
 
+**Standard spawn (no --sandbox):**
+
 ```bash
 # Spawn fresh Claude with the agent's system prompt and our handoff.
 # Unset CLAUDECODE so the child doesn't reject as "nested session" —
@@ -186,6 +190,41 @@ RESULT=$(unset CLAUDECODE && cat "$HANDOFF_FILE" | claude \
 EXIT_CODE=$?
 ```
 
+**Sandbox spawn (--sandbox flag present):**
+
+When `--sandbox` is detected in $ARGUMENTS, route through Docker instead:
+
+```bash
+# Verify Docker is available
+docker --version 2>/dev/null || {
+  echo "Docker not installed. Cannot use --sandbox. Run /merlin:sandbox for setup."
+  exit 1
+}
+
+# Verify image exists
+docker images merlin-sandbox:latest -q 2>/dev/null | grep -q . || {
+  echo "Sandbox image not built. Run /merlin:sandbox build first."
+  exit 1
+}
+
+# Spawn agent inside Docker sandbox
+# Project is mounted read-only. Agent writes results to /workspace-output.
+RESULT=$(docker run --rm \
+  --network none \
+  --cpus="2" \
+  --memory="4g" \
+  -v "$(pwd):/workspace:ro" \
+  -v "merlin-output:/workspace-output" \
+  -e "ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}" \
+  -e "MERLIN_API_KEY=${MERLIN_API_KEY:-}" \
+  merlin-sandbox:latest \
+  /bin/sh -c "cat > /tmp/handoff.md && unset CLAUDECODE && claude --agent {agent-name} -p --permission-mode acceptEdits --output-format text < /tmp/handoff.md" \
+  < "$HANDOFF_FILE" 2>&1)
+EXIT_CODE=$?
+```
+
+Note: In sandbox mode, the agent writes code to `/workspace-output`, not to the project directory. Inform the user they need to copy results out manually or use `/merlin:sandbox run` for a more guided experience.
+
 **Parameters explained:**
 - `--agent {agent-name}`: Loads agent system prompt from `~/.claude/agents/{agent-name}.md`
 - `-p`: Print mode — non-interactive, outputs result and exits
@@ -376,4 +415,7 @@ The orchestrator's context stays lean because:
 - Both modes get identical fresh-process treatment
 - Keep handoff files in /tmp — ephemeral, auto-cleaned on reboot
 - Max 10 minute timeout per spawn — for heavier work, use merlin-loop
+- `--sandbox` is optional — Docker is NOT required for normal Merlin operation
+- In sandbox mode, the project is mounted read-only; agent output goes to /workspace-output
+- Use `/merlin:sandbox build` to prepare the image before using --sandbox
 </design_notes>

package/files/commands/merlin/sandbox.md

@@ -0,0 +1,359 @@
+---
+name: merlin:sandbox
+description: Run agents inside a Docker sandbox — isolated, read-only project mount, resource-limited
+argument-hint: "build | run \"task\" | shell | status"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - AskUserQuestion
+---
+
+<objective>
+Docker-based sandboxed execution for running agents safely.
+
+Project is mounted read-only. Agent output goes to a writable volume at /workspace-output.
+No network access by default. CPU and memory are capped.
+
+Four sub-commands:
+- `build`  — Build the merlin-sandbox Docker image
+- `run`    — Run a task inside the sandbox via a fresh claude agent
+- `shell`  — Open an interactive shell inside the sandbox
+- `status` — Check if Docker is installed and image is built
+</objective>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+
+## Step 1: Parse Sub-Command
+
+Extract from $ARGUMENTS:
+- **sub-command**: First word (`build`, `run`, `shell`, `status`)
+- **task**: Everything after the sub-command (only relevant for `run`)
+
+If no arguments provided, show usage and exit:
+
+```
+Usage: /merlin:sandbox <sub-command> [options]
+
+Sub-commands:
+  build              Build the merlin-sandbox Docker image
+  run "task"         Run a task inside the sandbox
+  shell              Open an interactive shell in the sandbox
+  status             Check Docker availability and image status
+
+Examples:
+  /merlin:sandbox build
+  /merlin:sandbox run "refactor the auth module"
+  /merlin:sandbox shell
+  /merlin:sandbox status
+```
+
+## Step 2: Check Docker is Installed
+
+Run this check for ALL sub-commands before proceeding:
+
+```bash
+docker --version 2>/dev/null
+```
+
+If Docker is not installed or the command fails:
+
+```
+Docker is not installed or not running.
+
+Sandboxed execution requires Docker Desktop (or Docker Engine on Linux).
+
+Install: https://docs.docker.com/get-docker/
+
+Normal Merlin operation does not require Docker — /merlin:sandbox is optional.
+```
+
+Exit. Do not proceed with any sub-command.
+
+## Step 3: Route to Sub-Command
+
+### Sub-command: `status`
+
+Check if Docker daemon is running and whether the sandbox image exists:
+
+```bash
+docker info --format '{{.ServerVersion}}' 2>/dev/null
+docker images merlin-sandbox:latest --format '{{.Repository}}:{{.Tag}} ({{.Size}}, created {{.CreatedSince}})' 2>/dev/null
+```
+
+Display:
+
+```
+════════════════════════════════════════
+Merlin Sandbox Status
+════════════════════════════════════════
+
+Docker:          running (version {X.Y.Z})
+Image:           {built — merlin-sandbox:latest, ~NNN MB, created N days ago}
+                 OR {not built — run /merlin:sandbox build}
+
+Config:          ~/.claude/merlin/sandbox.json
+Network:         disabled (network_mode: none)
+CPU limit:       2 cores
+Memory limit:    4 GB
+Mount mode:      read-only
+Output volume:   merlin-output (writable at /workspace-output)
+────────────────────────────────────────
+```
+
+If image not built, append:
+```
+Run `/merlin:sandbox build` to build the image (takes ~2-3 minutes).
+```
+
+---
+
+### Sub-command: `build`
+
+Locate the Dockerfile. Check in this order:
+1. `~/.claude/merlin/docker/Dockerfile.merlin`
+2. `.merlin/docker/Dockerfile.merlin`
+
+```bash
+DOCKERFILE_PATH=""
+[ -f "$HOME/.claude/merlin/docker/Dockerfile.merlin" ] && DOCKERFILE_PATH="$HOME/.claude/merlin/docker/Dockerfile.merlin"
+[ -z "$DOCKERFILE_PATH" ] && [ -f ".merlin/docker/Dockerfile.merlin" ] && DOCKERFILE_PATH=".merlin/docker/Dockerfile.merlin"
+```
+
+If not found:
+```
+Dockerfile.merlin not found.
+
+Expected at: ~/.claude/merlin/docker/Dockerfile.merlin
+
+Try reinstalling Merlin: npx create-merlin-brain --yes
+```
+Exit.
+
+Build the image:
+
+```bash
+docker build \
+  -t merlin-sandbox:latest \
+  -f "$DOCKERFILE_PATH" \
+  "$(dirname "$DOCKERFILE_PATH")" \
+  2>&1
+```
+
+Use Bash tool with `timeout: 300000` (5 minutes — image build can take a while).
+
+On success:
+```
+════════════════════════════════════════
+Sandbox image built
+════════════════════════════════════════
+
+Image:    merlin-sandbox:latest
+Ready for: /merlin:sandbox run "task" | /merlin:sandbox shell
+────────────────────────────────────────
+```
+
+On failure, show the Docker build output and suggest:
+```
+Build failed. Common causes:
+- No internet connection during build (npm install needs network)
+- Docker daemon not running
+- Insufficient disk space
+
+Check `docker system df` for disk usage.
+```
+
+---
+
+### Sub-command: `run`
+
+Requires a task description after `run`. If missing:
+```
+Missing task description.
+
+Usage: /merlin:sandbox run "task description"
+
+Example: /merlin:sandbox run "refactor the payment module"
+```
+Exit.
+
+Check if image exists:
+```bash
+docker images merlin-sandbox:latest -q 2>/dev/null
+```
+
+If image is not built, prompt:
+```
+Sandbox image not found. Build it first?
+```
+Use AskUserQuestion. If user confirms, run the build step first (same as `build` sub-command), then proceed.
+
+Determine the project directory:
+```bash
+PROJECT_DIR=$(pwd)
+```
+
+Run the agent inside the sandbox:
+
+```bash
+docker run --rm \
+  --network none \
+  --cpus="2" \
+  --memory="4g" \
+  -v "${PROJECT_DIR}:/workspace:ro" \
+  -v "merlin-output:/workspace-output" \
+  -e "ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}" \
+  -e "MERLIN_API_KEY=${MERLIN_API_KEY:-}" \
+  merlin-sandbox:latest \
+  claude -p \
+    --permission-mode acceptEdits \
+    --output-format text \
+    -- "{task-description}" \
+  2>&1
+```
+
+Use Bash tool with `timeout: 600000` (10 minutes).
+
+After completion:
+
+1. Check exit code — non-zero is an error; show output and suggest `/merlin:sandbox shell` for debugging.
+
+2. Show a summary of any output files written:
+```bash
+docker run --rm -v "merlin-output:/workspace-output" \
+  alpine find /workspace-output -type f 2>/dev/null
+```
+
+3. Display result:
+```
+════════════════════════════════════════
+Sandbox run complete
+════════════════════════════════════════
+
+{agent output summary}
+
+Output files (at /workspace-output):
+{list of files or "none"}
+
+To copy output to current directory:
+docker run --rm \
+  -v merlin-output:/src \
+  -v "$(pwd)":/dst \
+  alpine cp -r /src/. /dst/sandbox-output/
+────────────────────────────────────────
+```
+
+---
+
+### Sub-command: `shell`
+
+Check if image exists (same check as `run`). Offer to build if missing.
+
+Open an interactive shell in the sandbox:
+
+```bash
+docker run --rm -it \
+  --network none \
+  --cpus="2" \
+  --memory="4g" \
+  -v "$(pwd):/workspace:ro" \
+  -v "merlin-output:/workspace-output" \
+  -e "ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}" \
+  -e "MERLIN_API_KEY=${MERLIN_API_KEY:-}" \
+  merlin-sandbox:latest \
+  /bin/bash 2>&1
+```
+
+Note before running:
+```
+Opening sandbox shell.
+
+Project mounted read-only at: /workspace
+Write output to:              /workspace-output
+
+Type 'exit' to leave the sandbox.
+```
+
+## Step 4: Error Display Format
+
+All errors use this format:
+
+```
+Sandbox error: {short description}
+
+{detail or Docker output}
+
+{suggested fix}
+```
+
+</process>
+
+<sandbox_notes>
+
+## What the sandbox does
+
+- Mounts your project read-only — the agent cannot modify your source files
+- Gives the agent a writable volume at /workspace-output for its results
+- Blocks all network access (network_mode: none)
+- Caps CPU at 2 cores and memory at 4 GB
+- Destroys the container after the run (--rm)
+- Never persists container state between runs
+
+## --sandbox flag in /merlin:route
+
+When routing agents with `/merlin:route`, pass `--sandbox` to route the task through the Docker sandbox instead of spawning a local process:
+
+```
+/merlin:route implementation-dev "refactor auth" --sandbox
+```
+
+This causes the orchestrator to use `docker run merlin-sandbox:latest claude --agent ...` instead of a bare `claude --agent ...` call. Requirements:
+
+- Docker must be installed and running
+- `merlin-sandbox:latest` image must be built (`/merlin:sandbox build`)
+- Project is mounted read-only — the agent writes results to /workspace-output
+- The flag is optional — normal routing does not require Docker
+
+## When to use the sandbox
+
+Use it when:
+- Running untrusted or experimental agent tasks
+- You want to guarantee the agent cannot modify source files
+- Running automated tasks in CI where isolation matters
+
+Do not use it for normal development work — the read-only mount means the agent
+cannot commit changes directly to your working directory.
+
+</sandbox_notes>
+
+<error_handling>
+
+| Condition | Action |
+|-----------|--------|
+| Docker not installed | Show install link, exit gracefully |
+| Docker daemon not running | Tell user to start Docker, exit |
+| Image not built | Offer to build, then proceed |
+| Build fails | Show Docker output, suggest common fixes |
+| Run times out (>10 min) | Warn: task too large for sandbox, suggest splitting |
+| No ANTHROPIC_API_KEY | Warn that agent will fail without the key |
+| No task in `run` | Show usage, exit |
+| Unknown sub-command | Show usage, exit |
+
+</error_handling>
+
+<success_criteria>
+- [ ] Docker check runs before any sub-command
+- [ ] Graceful error when Docker is not installed (does not crash Merlin)
+- [ ] `status` shows image existence and config
+- [ ] `build` produces merlin-sandbox:latest
+- [ ] `run` mounts project read-only, blocks network, caps resources
+- [ ] `shell` opens interactive bash in the container
+- [ ] Output files listed after a run
+- [ ] Normal Merlin operation is never blocked by Docker absence
+</success_criteria>

package/files/commands/merlin/usage.md

@@ -0,0 +1,55 @@
+---
+name: merlin:usage
+description: Show session usage report — per-agent cost breakdown, token counts, and savings vs all-Opus baseline
+allowed-tools:
+  - mcp__merlin__merlin_session_cost
+---
+
+<objective>
+Display a formatted usage report for the current session.
+
+Shows per-agent call counts, token usage, estimated cost, and how much was saved
+versus routing every task to Opus. Useful for auditing spend and verifying that
+cost-aware routing is working correctly.
+</objective>
+
+<process>
+
+## Step 1: Fetch session cost data
+
+Call `merlin_session_cost` to get the current session breakdown.
+
+## Step 2: Display the report
+
+If no routing calls have been recorded yet, show:
+
+```
+Usage Report
+
+No routing calls recorded yet.
+
+Costs are tracked automatically when merlin_route is used.
+Run /merlin:route or delegate a task to an agent to start tracking.
+```
+
+Otherwise, render the data returned by `merlin_session_cost` as-is — the tool
+already formats a complete markdown report including:
+
+- Per-agent table (calls, tokens in/out, estimated cost)
+- Per-model breakdown (Haiku / Sonnet / Opus)
+- Summary table with actual cost, Opus baseline, and savings
+
+After displaying, add a one-line tip:
+
+```
+Tip: Run /merlin:usage any time during a session to check your spend.
+```
+
+</process>
+
+<success_criteria>
+- [ ] Calls merlin_session_cost and displays output
+- [ ] Shows per-agent breakdown when routing calls exist
+- [ ] Graceful message when no calls recorded
+- [ ] Concise — output fits in a single scroll
+</success_criteria>

package/files/docker/Dockerfile.merlin

@@ -0,0 +1,20 @@
+FROM node:20-slim
+
+# Install essentials
+RUN apt-get update && apt-get install -y \
+  git curl jq bash \
+  && rm -rf /var/lib/apt/lists/*
+
+# Install Claude Code CLI
+RUN npm install -g @anthropic-ai/claude-code
+
+# Install Merlin
+RUN npx create-merlin-brain --yes 2>/dev/null || true
+
+# Create non-root user
+RUN useradd -m -s /bin/bash merlin
+USER merlin
+WORKDIR /workspace
+
+# Default: run Claude Code
+ENTRYPOINT ["claude"]

package/files/docker/docker-compose.merlin.yml

@@ -0,0 +1,23 @@
+version: '3.8'
+services:
+  merlin-sandbox:
+    build:
+      context: .
+      dockerfile: Dockerfile.merlin
+    volumes:
+      - ${PROJECT_DIR:-.}:/workspace:ro
+      - merlin-output:/workspace-output
+    environment:
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+      - MERLIN_API_KEY=${MERLIN_API_KEY}
+    network_mode: "none"  # No network by default
+    deploy:
+      resources:
+        limits:
+          cpus: '2'
+          memory: 4G
+    stdin_open: true
+    tty: true
+
+volumes:
+  merlin-output:

package/files/hook-templates/auto-commit.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+#
+# Hook Template: auto-commit.sh
+# Event: Stop
+#
+# Stages and commits all changes at the end of a Claude session.
+# Uses the session summary or a generic message as the commit message.
+#
+# HOW TO INSTALL:
+#   Copy this file to ~/.claude/merlin/hooks/auto-commit.sh
+#   Then add to your .claude/settings.local.json:
+#
+#   {
+#     "hooks": {
+#       "Stop": [
+#         {
+#           "hooks": [{ "type": "command", "command": "~/.claude/merlin/hooks/auto-commit.sh" }]
+#         }
+#       ]
+#     }
+#   }
+#
+# BEHAVIOR: Advisory only. Commits if there are staged/unstaged changes.
+# WARNING: This commits automatically — only enable if you trust auto-commits.
+#          Consider using changelog-reminder.sh instead for a softer nudge.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+# Only run if we're in a git repo
+git rev-parse --git-dir >/dev/null 2>&1 || { echo '{}'; exit 0; }
+
+# Check for changes
+if git diff --quiet && git diff --cached --quiet; then
+  echo "auto-commit: no changes to commit" >&2
+  echo '{}'
+  exit 0
+fi
+
+# Read stop hook input for session summary
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+# Try to extract stop reason or session summary from hook input
+commit_msg="chore: auto-commit by Claude Code session"
+if [ -n "$input" ] && command -v jq >/dev/null 2>&1; then
+  stop_reason=$(echo "$input" | jq -r '.stop_reason // empty' 2>/dev/null || true)
+  if [ -n "$stop_reason" ] && [ "$stop_reason" != "null" ]; then
+    commit_msg="chore: ${stop_reason}"
+  fi
+fi
+
+# Stage all changes
+git add -A
+
+# Commit
+git commit -m "$commit_msg" >/dev/null 2>&1 && \
+  echo "auto-commit: committed changes — \"$commit_msg\"" >&2 || \
+  echo "auto-commit: commit failed (pre-commit hook may have blocked)" >&2
+
+echo '{}'
+exit 0

package/files/hook-templates/auto-format.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+#
+# Hook Template: auto-format.sh
+# Event: PostToolUse (Write, Edit)
+#
+# Automatically runs Prettier and/or ESLint after Claude writes or edits a file.
+# Keeps code style consistent without manual intervention.
+#
+# HOW TO INSTALL:
+#   Copy this file to ~/.claude/merlin/hooks/auto-format.sh
+#   Then add to your .claude/settings.local.json:
+#
+#   {
+#     "hooks": {
+#       "PostToolUse": [
+#         {
+#           "matcher": "Write|Edit",
+#           "hooks": [{ "type": "command", "command": "~/.claude/merlin/hooks/auto-format.sh" }]
+#         }
+#       ]
+#     }
+#   }
+#
+# REQUIREMENTS: prettier and/or eslint must be installed in the project.
+# BEHAVIOR: Advisory only — never blocks. Runs format in background and exits.
+#
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+# Read tool input from stdin
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+[ -z "$input" ] && { echo '{}'; exit 0; }
+
+# Extract file path
+file_path=""
+if command -v jq >/dev/null 2>&1; then
+  file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null || true)
+fi
+
+[ -z "$file_path" ] || [ ! -f "$file_path" ] && { echo '{}'; exit 0; }
+
+# Only format code files
+case "$file_path" in
+  *.js|*.jsx|*.ts|*.tsx|*.mjs|*.cjs|*.json|*.css|*.scss|*.html|*.vue|*.svelte|*.md)
+    ;;
+  *)
+    echo '{}'
+    exit 0
+    ;;
+esac
+
+# Skip node_modules and generated files
+case "$file_path" in
+  *node_modules*|*.min.js|*.bundle.js|*dist/*|*build/*)
+    echo '{}'
+    exit 0
+    ;;
+esac
+
+# Try Prettier first (project-local, then global)
+PRETTIER=""
+if [ -f "node_modules/.bin/prettier" ]; then
+  PRETTIER="node_modules/.bin/prettier"
+elif command -v prettier >/dev/null 2>&1; then
+  PRETTIER="prettier"
+fi
+
+if [ -n "$PRETTIER" ]; then
+  $PRETTIER --write "$file_path" >/dev/null 2>&1 || true
+  echo "auto-format: prettier applied to $file_path" >&2
+fi
+
+# Try ESLint for JS/TS files (fix mode)
+case "$file_path" in
+  *.js|*.jsx|*.ts|*.tsx|*.mjs|*.cjs)
+    ESLINT=""
+    if [ -f "node_modules/.bin/eslint" ]; then
+      ESLINT="node_modules/.bin/eslint"
+    elif command -v eslint >/dev/null 2>&1; then
+      ESLINT="eslint"
+    fi
+
+    if [ -n "$ESLINT" ]; then
+      $ESLINT --fix "$file_path" >/dev/null 2>&1 || true
+      echo "auto-format: eslint --fix applied to $file_path" >&2
+    fi
+    ;;
+esac
+
+echo '{}'
+exit 0