{"slug":"parallel-worktree-agents","title":"Parallel Worktree Agents: N Competing Implementations from One Plan","tags":["claude-code","git","worktrees","parallel","agents","architecture"],"agent_summary":"Run multiple Claude Code agents in parallel git worktrees to generate competing implementations of a feature, then merge the best. Covers init, execute, compare, and merge phases.","trigger_phrases":["parallel worktree","competing implementations","parallel agents","git worktree agents","multiple Claude agents","parallel Claude Code"],"runnable":false,"markdown":"\n## Overview\n\nLLMs are non-deterministic. The same plan produces different results each run. Instead of running once and hoping, run N agents in parallel isolated environments and choose the best of N.\n\n## When to Use\n\n- You have a **clear written plan** (not iterative prompting)\n- The task is **ambiguous enough** that multiple valid solutions exist (UI work, architecture decisions)\n- You suspect the task is **hard enough** that one agent might fail\n- The work is **substantial enough** to justify its own branch\n\n**Do NOT use** for interactive iteration, trivial tasks, or when no written plan exists.\n\n## Three-Phase Workflow\n\n### Phase 1: Plan\n\nWrite a detailed spec/plan file in your codebase. All agents execute against this single file. The plan IS the prompt at scale.\n\n```markdown\n# Plan: Redesign Dashboard Layout\n\n## Goal\nRebuild the main dashboard with real-time stats, collapsible sidebar, and mobile-responsive grid.\n\n## Requirements\n- Stats row: 4 KPI cards (revenue, users, conversions, churn)\n- Sidebar: collapsible at 768px breakpoint\n- Charts: recharts, data from /api/metrics\n- Components: all in src/components/dashboard/\n...\n```\n\n### Phase 2: Initialize Worktrees\n\n```bash\n# Create N isolated environments\nmkdir -p trees\ngit worktree add trees/dashboard-v1 -b dashboard-v1\ngit worktree add trees/dashboard-v2 -b dashboard-v2\ngit worktree add trees/dashboard-v3 -b dashboard-v3\n\n# Copy environment into each\ncp .env trees/dashboard-v1/.env\ncp .env trees/dashboard-v2/.env\ncp .env trees/dashboard-v3/.env\n\n# Install deps in each\n(cd trees/dashboard-v1 && npm install)\n(cd trees/dashboard-v2 && npm install)\n(cd trees/dashboard-v3 && npm install)\n```\n\nEach worktree is a full clone of your codebase on its own git branch, running on a separate port.\n\n### Phase 3: Execute in Parallel\n\nLaunch N Claude Code sessions, one per worktree, each given the same plan file:\n\n```bash\n# Terminal 1\ncd trees/dashboard-v1\nclaude \"Execute the plan in PLAN.md. Build in this directory only. Write results.md when done.\"\n\n# Terminal 2\ncd trees/dashboard-v2\nclaude \"Execute the plan in PLAN.md. Build in this directory only. Write results.md when done.\"\n\n# Terminal 3\ncd trees/dashboard-v3\nclaude \"Execute the plan in PLAN.md. Build in this directory only. Write results.md when done.\"\n```\n\nAll three agents work simultaneously.\n\n## Comparing Results\n\n```bash\n# Boot all servers on different ports\n(cd trees/dashboard-v1 && PORT=5174 npm run dev &)\n(cd trees/dashboard-v2 && PORT=5175 npm run dev &)\n(cd trees/dashboard-v3 && PORT=5176 npm run dev &)\n\n# View side by side in browser\nopen http://localhost:5174\nopen http://localhost:5175\nopen http://localhost:5176\n```\n\nEach agent writes `results.md` summarizing what it did. Read these to understand tradeoffs before visually comparing.\n\n## Merging the Best\n\n```bash\n# Commit the winning worktree (e.g., v2)\ncd trees/dashboard-v2\ngit add -A && git commit -m \"Dashboard redesign - parallel agent v2\"\ngit push origin dashboard-v2\n\n# Merge into main\ngit checkout main\ngit merge dashboard-v2\n\n# Clean up\ngit worktree remove trees/dashboard-v1\ngit worktree remove trees/dashboard-v2\ngit worktree remove trees/dashboard-v3\ngit branch -d dashboard-v1 dashboard-v3\n```\n\n## Results File Convention\n\nInstruct each agent to write a `results.md` at the end:\n\n```markdown\n# Results\n\n## What I Built\n- Replaced static grid with CSS Grid (2-col desktop, 1-col mobile)\n- Used recharts LineChart for revenue trend\n- Sidebar collapse via useState + CSS transition\n\n## Decisions Made\n- Chose recharts over chart.js for smaller bundle size\n- Used localStorage for sidebar collapsed state persistence\n\n## What Could Be Better\n- Mobile breakpoint at 768px feels early; 640px might work better\n```\n\n## Cost Consideration\n\nRunning 3 parallel agents costs roughly 3x tokens versus one run. The value is in quality variance — for critical UI or architecture decisions, the best of 3 often beats 3x iterative attempts on one branch.\n\n## Slash Command Pattern\n\nDefine reusable slash commands in `.claude/commands/`:\n\n```markdown\n\nCreate N git worktrees under trees/ for parallel agent execution.\nCopy .env. Install deps. Use branch names: {task}-{n}.\n```\n\n```markdown\n\nExecute $PLAN across all worktrees in trees/.\nSpin up one sub-agent per worktree. Pass the plan path.\nEach agent writes results.md when done.\n```\n","html":"

Overview

\n

LLMs are non-deterministic. The same plan produces different results each run. Instead of running once and hoping, run N agents in parallel isolated environments and choose the best of N.

\n

When to Use

\n\n

Do NOT use for interactive iteration, trivial tasks, or when no written plan exists.

\n

Three-Phase Workflow

\n

Phase 1: Plan

\n

Write a detailed spec/plan file in your codebase. All agents execute against this single file. The plan IS the prompt at scale.

\n
# Plan: Redesign Dashboard Layout\n\n## Goal\nRebuild the main dashboard with real-time stats, collapsible sidebar, and mobile-responsive grid.\n\n## Requirements\n- Stats row: 4 KPI cards (revenue, users, conversions, churn)\n- Sidebar: collapsible at 768px breakpoint\n- Charts: recharts, data from /api/metrics\n- Components: all in src/components/dashboard/\n...\n
\n

Phase 2: Initialize Worktrees

\n
# Create N isolated environments\nmkdir -p trees\ngit worktree add trees/dashboard-v1 -b dashboard-v1\ngit worktree add trees/dashboard-v2 -b dashboard-v2\ngit worktree add trees/dashboard-v3 -b dashboard-v3\n\n# Copy environment into each\ncp .env trees/dashboard-v1/.env\ncp .env trees/dashboard-v2/.env\ncp .env trees/dashboard-v3/.env\n\n# Install deps in each\n(cd trees/dashboard-v1 && npm install)\n(cd trees/dashboard-v2 && npm install)\n(cd trees/dashboard-v3 && npm install)\n
\n

Each worktree is a full clone of your codebase on its own git branch, running on a separate port.

\n

Phase 3: Execute in Parallel

\n

Launch N Claude Code sessions, one per worktree, each given the same plan file:

\n
# Terminal 1\ncd trees/dashboard-v1\nclaude \"Execute the plan in PLAN.md. Build in this directory only. Write results.md when done.\"\n\n# Terminal 2\ncd trees/dashboard-v2\nclaude \"Execute the plan in PLAN.md. Build in this directory only. Write results.md when done.\"\n\n# Terminal 3\ncd trees/dashboard-v3\nclaude \"Execute the plan in PLAN.md. Build in this directory only. Write results.md when done.\"\n
\n

All three agents work simultaneously.

\n

Comparing Results

\n
# Boot all servers on different ports\n(cd trees/dashboard-v1 && PORT=5174 npm run dev &)\n(cd trees/dashboard-v2 && PORT=5175 npm run dev &)\n(cd trees/dashboard-v3 && PORT=5176 npm run dev &)\n\n# View side by side in browser\nopen http://localhost:5174\nopen http://localhost:5175\nopen http://localhost:5176\n
\n

Each agent writes results.md summarizing what it did. Read these to understand tradeoffs before visually comparing.

\n

Merging the Best

\n
# Commit the winning worktree (e.g., v2)\ncd trees/dashboard-v2\ngit add -A && git commit -m \"Dashboard redesign - parallel agent v2\"\ngit push origin dashboard-v2\n\n# Merge into main\ngit checkout main\ngit merge dashboard-v2\n\n# Clean up\ngit worktree remove trees/dashboard-v1\ngit worktree remove trees/dashboard-v2\ngit worktree remove trees/dashboard-v3\ngit branch -d dashboard-v1 dashboard-v3\n
\n

Results File Convention

\n

Instruct each agent to write a results.md at the end:

\n
# Results\n\n## What I Built\n- Replaced static grid with CSS Grid (2-col desktop, 1-col mobile)\n- Used recharts LineChart for revenue trend\n- Sidebar collapse via useState + CSS transition\n\n## Decisions Made\n- Chose recharts over chart.js for smaller bundle size\n- Used localStorage for sidebar collapsed state persistence\n\n## What Could Be Better\n- Mobile breakpoint at 768px feels early; 640px might work better\n
\n

Cost Consideration

\n

Running 3 parallel agents costs roughly 3x tokens versus one run. The value is in quality variance — for critical UI or architecture decisions, the best of 3 often beats 3x iterative attempts on one branch.

\n

Slash Command Pattern

\n

Define reusable slash commands in .claude/commands/:

\n
<!-- .claude/commands/init-parallel.md -->\nCreate N git worktrees under trees/ for parallel agent execution.\nCopy .env. Install deps. Use branch names: {task}-{n}.\n
\n
<!-- .claude/commands/exe-parallel.md -->\nExecute $PLAN across all worktrees in trees/.\nSpin up one sub-agent per worktree. Pass the plan path.\nEach agent writes results.md when done.\n
\n"}