---
name: Git Worktrees Parallel
description: |
  Pattern for exploring multiple futures in parallel using git worktrees.
  Fire same task at multiple branches, pick best result.

  WHEN TO USE:
  - "Try multiple approaches"
  - "Parallel implementation"
  - "Multiple futures pattern"
  - "Git worktrees for agents"
  - Need to explore different solutions
  - Uncertain which approach is best
  - Want to A/B test implementations

  CAPABILITIES:
  - Create parallel worktrees
  - Fire agents at same task
  - Compare results
  - Merge best outcome

allowed-tools:
  - Read
  - Bash
---

# Git Worktrees Parallel

## Purpose

Don't commit to one approach. Create multiple parallel branches, fire agents at the same task, and pick the best result. Git worktrees enable true parallel exploration.

## Core Concept

```
                    main
                      │
         ┌────────────┼────────────┐
         ▼            ▼            ▼
    worktree-a    worktree-b   worktree-c
    (Approach A)  (Approach B)  (Approach C)
         │            │            │
    [Agent A]    [Agent B]    [Agent C]
         │            │            │
         └────────────┼────────────┘
                      ▼
              Compare Results
                      │
                      ▼
              Merge Best → main
```

## What Are Git Worktrees?

Git worktrees let you have multiple working directories from the same repository, each on a different branch. No switching branches - truly parallel.

```bash
# Traditional: One directory, switch branches
git checkout feature-a
# work...
git checkout feature-b
# lose feature-a context

# Worktrees: Multiple directories, parallel branches
./main/           # main branch
./trees/feature-a # feature-a branch
./trees/feature-b # feature-b branch
# Work on all simultaneously!
```

## Setup Workflow

### 1. Create Worktrees

```bash
# From your main repo directory
mkdir -p trees

# Create worktrees for parallel exploration
git worktree add ./trees/approach-a -b approach-a
git worktree add ./trees/approach-b -b approach-b
git worktree add ./trees/approach-c -b approach-c
```

### 2. Fire Agents in Parallel

```bash
# Terminal 1: Agent A
cd ./trees/approach-a
claude "Implement feature using pattern A"

# Terminal 2: Agent B
cd ./trees/approach-b
claude "Implement feature using pattern B"

# Terminal 3: Agent C
cd ./trees/approach-c
claude "Implement feature using pattern C"
```

### 3. Compare Results

```bash
# See what each approach produced
diff ./trees/approach-a/src ./trees/approach-b/src
diff ./trees/approach-a/src ./trees/approach-c/src

# Run tests on each
(cd ./trees/approach-a && npm test)
(cd ./trees/approach-b && npm test)
(cd ./trees/approach-c && npm test)
```

### 4. Pick and Merge Winner

```bash
# Approach B was best
cd ./main
git merge approach-b

# Clean up worktrees
git worktree remove ./trees/approach-a
git worktree remove ./trees/approach-b
git worktree remove ./trees/approach-c

# Delete unused branches
git branch -d approach-a approach-c
```

## Use Cases

### 1. Uncertain Implementation
When you don't know the best approach:
- Create 3 worktrees
- Each tries different architecture
- Run tests, compare quality
- Merge winner

### 2. Refactoring Options
When refactoring could go many ways:
- One worktree: minimal changes
- One worktree: major restructure
- One worktree: complete rewrite
- Compare outcomes

### 3. Performance Exploration
When optimizing:
- Each worktree tries different optimization
- Benchmark all
- Merge fastest

### 4. Bug Fix Approaches
When root cause is unclear:
- Each worktree tries different fix
- See which actually solves it
- Merge correct fix

## Parallel Agent Pattern

```python
import subprocess
from concurrent.futures import ThreadPoolExecutor

def run_agent_in_worktree(worktree_path, prompt):
    """Run Claude agent in a worktree"""
    result = subprocess.run(
        ["claude", "-p", prompt],
        cwd=worktree_path,
        capture_output=True,
        text=True
    )
    return {
        "path": worktree_path,
        "output": result.stdout,
        "returncode": result.returncode
    }

# Fire 3 agents in parallel
worktrees = [
    ("./trees/approach-a", "Implement using pattern A"),
    ("./trees/approach-b", "Implement using pattern B"),
    ("./trees/approach-c", "Implement using pattern C"),
]

with ThreadPoolExecutor(max_workers=3) as executor:
    futures = [
        executor.submit(run_agent_in_worktree, path, prompt)
        for path, prompt in worktrees
    ]
    results = [f.result() for f in futures]
```

## Evaluation Criteria

When comparing worktree results:

| Criterion | How to Check |
|-----------|--------------|
| Tests Pass | `npm test` / `pytest` exit code |
| Code Quality | `eslint` / `ruff` score |
| Performance | Benchmark execution time |
| Simplicity | Line count, cyclomatic complexity |
| Correctness | Manual review, edge case tests |

## Best Practices

1. **Same Starting Point**
   - All worktrees branch from same commit
   - Fair comparison

2. **Same Tests**
   - Use identical test suite
   - Consistent evaluation

3. **Clean Up**
   - Remove worktrees after decision
   - Delete unused branches
   - Keep repo clean

4. **Document Choice**
   - Note why winner was chosen
   - Future reference

## Commands Reference

```bash
# List worktrees
git worktree list

# Create worktree
git worktree add <path> -b <branch>

# Remove worktree
git worktree remove <path>

# Prune stale worktrees
git worktree prune
```

## References

See `references/` for advanced patterns and automation scripts.
