Overview
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.
When to Use
- You have a clear written plan (not iterative prompting)
- The task is ambiguous enough that multiple valid solutions exist (UI work, architecture decisions)
- You suspect the task is hard enough that one agent might fail
- The work is substantial enough to justify its own branch
Do NOT use for interactive iteration, trivial tasks, or when no written plan exists.
Three-Phase Workflow
Phase 1: Plan
Write a detailed spec/plan file in your codebase. All agents execute against this single file. The plan IS the prompt at scale.
# Plan: Redesign Dashboard Layout
## Goal
Rebuild the main dashboard with real-time stats, collapsible sidebar, and mobile-responsive grid.
## Requirements
- Stats row: 4 KPI cards (revenue, users, conversions, churn)
- Sidebar: collapsible at 768px breakpoint
- Charts: recharts, data from /api/metrics
- Components: all in src/components/dashboard/
...
Phase 2: Initialize Worktrees
# Create N isolated environments
mkdir -p trees
git worktree add trees/dashboard-v1 -b dashboard-v1
git worktree add trees/dashboard-v2 -b dashboard-v2
git worktree add trees/dashboard-v3 -b dashboard-v3
# Copy environment into each
cp .env trees/dashboard-v1/.env
cp .env trees/dashboard-v2/.env
cp .env trees/dashboard-v3/.env
# Install deps in each
(cd trees/dashboard-v1 && npm install)
(cd trees/dashboard-v2 && npm install)
(cd trees/dashboard-v3 && npm install)
Each worktree is a full clone of your codebase on its own git branch, running on a separate port.
Phase 3: Execute in Parallel
Launch N Claude Code sessions, one per worktree, each given the same plan file:
# Terminal 1
cd trees/dashboard-v1
claude "Execute the plan in PLAN.md. Build in this directory only. Write results.md when done."
# Terminal 2
cd trees/dashboard-v2
claude "Execute the plan in PLAN.md. Build in this directory only. Write results.md when done."
# Terminal 3
cd trees/dashboard-v3
claude "Execute the plan in PLAN.md. Build in this directory only. Write results.md when done."
All three agents work simultaneously.
Comparing Results
# Boot all servers on different ports
(cd trees/dashboard-v1 && PORT=5174 npm run dev &)
(cd trees/dashboard-v2 && PORT=5175 npm run dev &)
(cd trees/dashboard-v3 && PORT=5176 npm run dev &)
# View side by side in browser
open http://localhost:5174
open http://localhost:5175
open http://localhost:5176
Each agent writes results.md summarizing what it did. Read these to understand tradeoffs before visually comparing.
Merging the Best
# Commit the winning worktree (e.g., v2)
cd trees/dashboard-v2
git add -A && git commit -m "Dashboard redesign - parallel agent v2"
git push origin dashboard-v2
# Merge into main
git checkout main
git merge dashboard-v2
# Clean up
git worktree remove trees/dashboard-v1
git worktree remove trees/dashboard-v2
git worktree remove trees/dashboard-v3
git branch -d dashboard-v1 dashboard-v3
Results File Convention
Instruct each agent to write a results.md at the end:
# Results
## What I Built
- Replaced static grid with CSS Grid (2-col desktop, 1-col mobile)
- Used recharts LineChart for revenue trend
- Sidebar collapse via useState + CSS transition
## Decisions Made
- Chose recharts over chart.js for smaller bundle size
- Used localStorage for sidebar collapsed state persistence
## What Could Be Better
- Mobile breakpoint at 768px feels early; 640px might work better
Cost Consideration
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.
Slash Command Pattern
Define reusable slash commands in .claude/commands/:
<!-- .claude/commands/init-parallel.md -->
Create N git worktrees under trees/ for parallel agent execution.
Copy .env. Install deps. Use branch names: {task}-{n}.
<!-- .claude/commands/exe-parallel.md -->
Execute $PLAN across all worktrees in trees/.
Spin up one sub-agent per worktree. Pass the plan path.
Each agent writes results.md when done.