Worktrees

Principle

A git worktree creates a second (or third) working directory from the same repository, each checked out on a distinct branch. No git stash, no branch switching — two terminals, two contexts, zero friction between them.

Available since Git 2.5.0 (2015), natively compatible with Claude Code.

Essential commands

# Create a worktree on an existing or new branch
git worktree add ../myproject-feature feature/auth
git worktree add ../myproject-hotfix -b hotfix/login-bug

# List all active worktrees
git worktree list

# Clean up after merge
git worktree remove ../myproject-hotfix
git worktree prune   # Remove stale references

Parallel Claude Code pattern

# Terminal 1: main feature
cd ../myproject-feature
claude
> "Implement JWT authentication"

# Terminal 2: urgent hotfix (simultaneous)
cd ../myproject-hotfix
claude
> "Fix the timeout bug on Safari"

Each Claude instance indexes its own worktree and maintains an independent context. Both sessions run in parallel without interference.

Claude Code context in worktrees

A worktree can have its own .claude/ configuration for branch-specific conventions.

Dependency management

The main limitation: node_modules or vendor/ are not shared automatically. Each worktree needs its own dependencies, which can take disk space and time.

Recommended solution — symlink node_modules from the main worktree:

cd ../myproject-feature
ln -s ../myproject/node_modules node_modules

The /git-worktree custom command does this automatically. Use --isolated when dependencies must differ.

When to use worktrees

Suited for: multiple features in parallel, comparing approaches, code review during development, long CI builds while continuing to code.

Not suited for: simple and quick branch switches, teams unfamiliar with the tool (adds operational complexity), limited disk space.

Shell aliases for quick navigation

# In ~/.zshrc
alias wa="cd ../myproject-feature-a"
alias wb="cd ../myproject-feature-b"
alias wm="cd ../myproject"   # Main worktree

Pattern used by the Claude Code team internally to navigate instantly between active worktrees.

Cleanup after merge

After merging the branch, remove the worktree to free up space. git worktree prune cleans references to worktrees that were manually deleted (folder removed without going through git worktree remove).