Worktrees

Coordinate multiple Claude agents working in parallel on the same codebase using git worktrees.

Key Concept

Workers are separate Claude sessions, not subagents. The Manager creates worktrees, then the user opens a new terminal in each worktree and runs claude. Each Claude instance operates independently.

Concepts

•PLAN.md — Coordination document listing workstreams, file ownership, and decisions
•STATUS-{name}.md — Progress updates from each workstream (REQUIRED before merge)
•Manager — Plans on main branch, creates/merges worktrees, monitors progress
•Worker — Executes in worktree, respects file ownership, writes status

Determine Your Role

bash

git branch --show-current

•main or master → Manager
•wt/* branch → Worker for that workstream

Manager Workflow

1. Pre-Flight Checklist

Before creating worktrees, ensure:

• Foundation code committed on main
• pnpm install (or npm/yarn) works
• pnpm build passes
• Shared files ready (types, utils, mock data)
• No file ownership overlap between planned workstreams

2. Plan Workstreams

Create PLAN.md in project root. See references/plan-template.md for structure.

Critical: Define explicit file ownership to prevent merge conflicts. Be specific:

code

Good: apps/web/components/layout/*, apps/web/app/(dashboard)/layout.tsx
Bad:  apps/web/**  # Too broad, will conflict

3. Create Worktrees

bash

git worktree add ../projectname-{name} -b wt/{name}
cd ../projectname-{name} && pnpm install  # Install deps in each

Then tell the user:

code

Worktrees ready. Start workers:
  cd ~/projectname-{name} && claude
  cd ~/projectname-{other} && claude

4. Monitor Progress (Heartbeat)

Periodically check worker status:

bash

# Quick status check
echo "=== COMMITS ===" && git log wt/* --oneline -3
echo "=== STATUS FILES ===" && cat STATUS-*.md 2>/dev/null || echo "None yet"
echo "=== UNCOMMITTED ===" && for d in ../projectname-*; do echo "$d:"; git -C "$d" status --short | head -5; done

5. Merge and Cleanup

Only merge when STATUS file shows "Ready for merge: yes" and build passes.

bash

# Verify build in worktree first
cd ../projectname-{name}/apps/web && pnpm build

# Merge (back on main)
cd /path/to/main
git merge wt/{name} -m "Merge wt/{name}: Brief description"

# Cleanup
git worktree remove ../projectname-{name} --force
git branch -d wt/{name}

6. Update PLAN.md

Move completed workstream to "Completed Workstreams" section.

Worker Workflow

1. Orientation (Start of Session)

When you see you're on a wt/* branch:

code

You are Worker for `wt/{name}`.

1. Read PLAN.md for your scope and file ownership
2. ONLY modify files listed under your "Owns:" section
3. Commit frequently with clear messages
4. Write STATUS-{name}.md when done (REQUIRED)

Then:

•Read PLAN.md — find your workstream, understand scope
•Read STATUS-{name}.md if it exists (resuming previous session)

2. While Working

•Only modify files assigned to your workstream — this is critical
•Commit early and often (every logical chunk)
•If you need something from another workstream, note it as a blocker

3. Before Finishing (REQUIRED)

Write STATUS-{name}.md in project root. See references/status-template.md.

Do not consider work complete without a STATUS file.

bash

# Final steps
pnpm build  # Verify build passes
git add . && git commit -m "Add worker status file"

File Ownership Rules

Merge conflicts kill productivity. Strict ownership prevents them.

Pattern	Risk
`components/sidebar/*`	Safe — specific directory
`lib/utils.ts`	Safe — specific file
`components/**`	Dangerous — too broad
`*.ts`	Dangerous — overlaps everything

If two workstreams might touch the same file, either:

•Assign it to one workstream only
•Put it in "Shared Files (Manager Only)" section
•Split the file first

Quick Reference

Command	Purpose
`git worktree add ../proj-api -b wt/api`	Create worktree
`git worktree list`	List all worktrees
`git log wt/* --oneline -3`	Check recent commits
`git worktree remove ../proj-api --force`	Remove worktree
`git branch -d wt/api`	Delete branch after merge

Troubleshooting

Worker can't read/write files: Check you're in the right directory. Worktrees are sibling directories, not subdirectories.

Merge conflicts: File ownership wasn't specific enough. Resolve manually, then tighten ownership rules for next time.

Worker didn't write STATUS: Work is not complete. Ask them to write it before merging.

Build fails after merge: Run build in each worktree before merging. Merge in dependency order (shared code first).