name: git-worktrees description: > [STATUS: review] [CONFIDENCE: high] [REVIEWED: 2026-03-13] USE when needing isolated workspace for experiments or parallel development. Triggers: worktree, experiment, parallel branch, isolated copy, isolated branch, parallel work.

Skill: Git Worktrees

When to Load

• Experiment with uncertain outcome (may require rollback)
• Parallel work on 2+ tasks
• Large refactor while needing to keep a working version

Principle

Worktree = isolated working copy. Cheaper than stash/switch, safer than working in one tree.

Decision Matrix: branch vs worktree

Rule: worktree = recommendation, not mandate. Regular branch covers 80% of cases.

Workflow

1. Create worktree

# EnterWorktree creates a worktree automatically (Claude Code built-in)
# Or manually:
git worktree add ../project-experiment feature/experiment
cd ../project-experiment

2. Work in worktree

• Worktree = full working copy with a separate HEAD
• Can work in parallel in main tree and worktree
• Commits in the worktree go to their own branch

3. Merge result

# From the main tree:
git merge feature/experiment
# Or cherry-pick specific commits:
git cherry-pick <commit-hash>

4. Cleanup

git worktree remove ../project-experiment
# Or if branch is no longer needed:
git worktree remove ../project-experiment
git branch -d feature/experiment

Claude Code Integration

Claude Code has a built-in EnterWorktree tool:

• Automatically creates a worktree in a sibling directory
• Switches context to the new tree
• After completion — merge and cleanup

When to use EnterWorktree:

1. Plan contains 5+ steps with high risk of cascading errors
2. User asks to "try it, but keep rollback possible"
3. Parallel task while current one is unfinished

Anti-patterns

Gotchas

• Always git stash before creating worktree if you have uncommitted changes
• Worktree cleanup is manual — delete the directory when done