Worktree Mastery

Worktree Mastery

Run 3-5 parallel Claude sessions on same repo. "The single biggest productivity unlock." - Boris Cherny

Core Concept

Git worktrees = independent working directories sharing one repo. Each Claude session gets its own worktree. No branch conflicts, no stash juggling.

Quick Setup

# From repo root, create worktrees
git worktree add ../myproject-review main
git worktree add ../myproject-refactor main
git worktree add ../myproject-test main

# List active worktrees
git worktree list

Naming Convention

myproject/           # Main worktree (original clone)
myproject-review/    # Code review session
myproject-refactor/  # Refactoring session
myproject-test/      # Test writing session
myproject-docs/      # Documentation session

Session Strategy

Workflow

1. Create worktrees before starting parallel work 2. Start Claude in each worktree directory 3. Work independently - each session has isolated state 4. Sync via git - commit in one, pull in another 5. Cleanup when done

Sync Between Sessions

# In worktree needing updates
git fetch origin
git rebase origin/main

# Or if working on branches
git checkout feature-branch
git pull

References

• worktree-commands.md - Full command reference
• session-strategies.md - Multi-session patterns
• cleanup.md - Removal and maintenance

Cleanup

Remove Worktrees

# Remove worktree (fails if uncommitted changes)
git worktree remove ../repo-review

# Force remove (discards changes)
git worktree remove --force ../repo-scratch

Prune Stale References

After manually deleting worktree directories:

# Clean up stale worktree metadata
git worktree prune

# Dry run first
git worktree prune --dry-run

# Verbose output
git worktree prune -v

Full Cleanup Script

#!/bin/bash
# cleanup-worktrees.sh

# List current worktrees
echo "Current worktrees:"
git worktree list

# Remove all non-main worktrees
for wt in $(git worktree list --porcelain | grep "^worktree" | cut -d' ' -f2); do
  if [[ "$wt" != "$(pwd)" ]]; then
    echo "Removing: $wt"
    git worktree remove --force "$wt" 2>/dev/null || true
  fi
done

# Prune stale references
git worktree prune -v

echo "Remaining:"
git worktree list

Cleanup Checklist

Before removing worktrees:

• [ ] Commit or stash valuable changes
• [ ] Push branches you want to keep
• [ ] Check for untracked files worth saving

Disk Space Recovery

Worktrees share .git but duplicate working files.

# Check worktree sizes
du -sh ../project-*

# After removal, git gc for full cleanup
git gc --prune=now

Troubleshooting

"worktree is locked"

git worktree unlock ../locked-worktree
git worktree remove ../locked-worktree

"not a valid worktree"

Directory deleted manually. Prune metadata:

git worktree prune

Branch still exists after removal

Worktree removal doesn't delete branches:

# Delete local branch after worktree removal
git branch -d feature-branch

# Force delete if unmerged
git branch -D feature-branch

Session Strategies

Recommended Setup: 3-5 Worktrees

Sweet spot for most projects. More adds overhead, fewer limits parallelism.

Standard Configuration

project/              # Main: commits, primary work
project-review/       # Reviews: PRs, code reading
project-refactor/     # Heavy lifting: large changes
project-test/         # Testing: write tests, debug
project-scratch/      # Throwaway: experiments

Session Isolation Benefits

Each Claude session in separate worktree:

• No conflicts - Different files, different branches
• Context preserved - Each session maintains own state
• Safe experiments - Trash one without affecting others
• Parallel progress - Review PR while feature develops

Coordination Patterns

Primary + Satellites

One main worktree for commits, others for auxiliary work.

[main]     ──commits──> origin
[review]   reads from main
[refactor] PRs back to main

Feature Branches

Each worktree on different feature branch.

[main]        on main
[feature-a]   on feature-a branch
[feature-b]   on feature-b branch

Review Pipeline

[dev]      Write code
[review]   Self-review before PR
[test]     Verify behavior

Communication Between Sessions

Worktrees share git history. Coordinate via commits:

# Session A: commit work
git add . && git commit -m "WIP: feature progress"

# Session B: pull changes
git fetch && git rebase origin/main

Context Switching

When moving between worktrees:

1. Don't cd - Open new terminal in worktree directory 2. Separate shells - One terminal per worktree 3. Name terminals - Match worktree names for clarity

When NOT to Use Multiple Worktrees

• Tiny changes (single file edits)
• Sequential tasks (no parallelism benefit)
• Limited disk space (each worktree = full checkout)

Worktree Commands

Create Worktrees

# Create from current branch
git worktree add ../repo-name-suffix

# Create from specific branch
git worktree add ../repo-review main

# Create with new branch
git worktree add -b feature-x ../repo-feature main

# Create detached (no branch)
git worktree add --detach ../repo-experiment HEAD

List and Inspect

# List all worktrees
git worktree list

# Verbose output with branch info
git worktree list --porcelain

Lock/Unlock

Prevent accidental removal:

# Lock a worktree
git worktree lock ../repo-important

# Unlock when done
git worktree unlock ../repo-important

# Lock with reason
git worktree lock --reason "Long-running refactor" ../repo-refactor

Move Worktrees

# Relocate worktree directory
git worktree move ../old-path ../new-path

Repair

Fix broken worktree references:

# Repair all worktrees
git worktree repair

# Repair specific path
git worktree repair ../broken-worktree

Common Patterns

Parallel Feature Development

git worktree add -b feature-a ../repo-feature-a main
git worktree add -b feature-b ../repo-feature-b main

Quick PR Review

git worktree add ../repo-pr-123 origin/pr-branch
# Review, then remove
git worktree remove ../repo-pr-123

Experimental Work

git worktree add --detach ../repo-experiment HEAD
# Experiment freely
# Discard or cherry-pick results
git worktree remove --force ../repo-experiment