Parallel Worktrees

# Create isolated worktree and start session
claude -w

# Claude Code auto-creates, manages, and cleans up the worktree
# Each session gets its own isolated working copy

# Manually create worktrees
git worktree add ../project-feat feature-branch
git worktree add ../project-fix bugfix-branch

# Open each worktree in a separate editor window
code ../project-feat
code ../project-fix

Terminal 1: ~/project          → Main work (feature development)
Terminal 2: ~/project-feat     → Feature branch (parallel feature)
Terminal 3: ~/project-fix      → Bug fixes (urgent fix while tests run)

# From existing branch
git worktree add ../project-feat feature-branch

# Create new branch
git worktree add ../project-exp -b experiment

# From specific commit
git worktree add ../project-hotfix abc123 -b hotfix/critical-bug

# With custom path
git worktree add /tmp/project-temp main

git worktree list

# Verbose (show locked status)
git worktree list --porcelain

# Remove specific worktree
git worktree remove ../project-feat

# Force remove (even with uncommitted changes)
git worktree remove ../project-feat --force

# Clean up stale references
git worktree prune

# From any location
git -C ../project-feat status
git -C ../project-feat log --oneline -5

# Claude Code handles everything
claude -w

# Behind the scenes:
# 1. Creates worktree in temp location
# 2. Checks out current or new branch
# 3. Opens session in worktree
# 4. Cleans up on exit

# Send current task to background
Ctrl+B

# Kill all background agents
Ctrl+F  # Press twice to confirm

# Background agents appear in session list
claude sessions

---
name: scout
description: Explore codebase for patterns
background: true
isolation: worktree
---

# Terminal 1: Main session
$ npm test
# ... tests running (2 minutes) ...

# Terminal 2: Create worktree for parallel work
$ git worktree add ../project-feat -b feat/new-endpoint
Preparing worktree (new branch 'feat/new-endpoint')
HEAD is now at a3f5c21 feat: add user auth

$ cd ../project-feat
$ claude

Claude: What should we work on?

User: Implement the new API endpoint for user preferences

Claude: [Implements feature while tests run in main session]

# Terminal 1: Tests complete
✓ All tests passed

# Return to main session, handle test results
# Worktree session continues independently

# Try 3 different approaches in parallel

$ git worktree add ../project-approach-1 -b experiment/approach-1
$ git worktree add ../project-approach-2 -b experiment/approach-2
$ git worktree add ../project-approach-3 -b experiment/approach-3

# Open each in separate terminal/editor
# Implement different solutions
# Compare results, keep the best one
# Delete the others

$ git worktree remove ../project-approach-2
$ git worktree remove ../project-approach-3
$ git branch -D experiment/approach-2 experiment/approach-3

# Terminal 1: Review PR in read-only worktree
$ git worktree add ../project-review pr-branch
$ cd ../project-review
$ claude

Claude: Reviewing PR changes in read-only mode...

# Terminal 2: Continue development on main branch
$ cd ~/project
$ claude

Claude: Implementing new feature...

# Both sessions work independently

# Main session working on feature
$ cd ~/project
# ... feature development in progress ...

# Urgent bug report comes in
$ git worktree add ../project-hotfix -b hotfix/critical-bug main
$ cd ../project-hotfix
$ claude

User: Fix the critical authentication bug

Claude: [Fixes bug, tests, commits]

$ git push origin hotfix/critical-bug
# Create PR for immediate merge

# Return to main session, continue feature work
$ cd ~/project

# Error: 'feature-branch' is already checked out at '/Users/you/project'

# Solution: Use a different branch or create new branch
git worktree add ../project-feat -b feature-branch-2

# Force remove
git worktree remove ../project-feat --force

# Then prune
git worktree prune

# List all worktrees
git worktree list

# Remove all except main
git worktree list | grep -v "$(pwd)" | awk '{print $1}' | xargs -I {} git worktree remove {}

# Check disk usage
du -sh ../project*

# Clean up node_modules in worktrees
find ../project-* -name "node_modules" -type d -prune -exec rm -rf {} +

---
name: scout
description: PROACTIVELY explore codebase when confidence is low
tools: ["Read", "Glob", "Grep"]
background: true
isolation: worktree
model: haiku
---

You are a scout agent. Explore the codebase to:
1. Find similar patterns
2. Identify relevant files
3. Score confidence (0-100)
4. Report back with findings

Never make changes. Read-only exploration.

---
name: reviewer
description: Code review with security focus
tools: ["Read", "Grep", "Bash"]
isolation: worktree
model: opus
---

Review changes in this worktree:
1. Security vulnerabilities
2. Performance issues
3. Test coverage
4. Code quality

Never modify code. Report findings only.