Worktrees

Git worktrees let you have multiple working directories for the same repository, each on a different branch. This enables parallel work without stashing or switching.

The problem worktrees solve

You are mid-feature on a branch, tests are broken, files are modified. A critical bug comes in. Without worktrees, you either stash everything (risky) or commit half-done work (messy). With worktrees, you create a separate directory for the fix.

How Claude Code uses worktrees

Claude Code can run subagents in isolated worktrees using the --worktree flag:

Launch an agent in a worktree to investigate the session timeout bug
while I continue working on the feature here.

The subagent gets its own copy of the repo on a separate branch. Changes it makes do not affect your working directory. When it finishes, you can review its changes and merge them.

When to use worktrees

The —worktree flag

Claude Code has built-in worktree support:

# Create a named worktree and start Claude in it
claude --worktree feature-auth

# With tmux for background sessions
claude --worktree feature-auth --tmux

This creates a worktree at .claude/worktrees/feature-auth/ and starts Claude inside it. The worktree is automatically on its own branch with full isolation from your main working directory.

Manual worktree usage

# Create a worktree for a hotfix
git worktree add ../myproject-hotfix hotfix/session-timeout

# Work in it
cd ../myproject-hotfix
claude  # Start Claude Code in the worktree

# Clean up when done
git worktree remove ../myproject-hotfix

Scaling to multiple instances

The real power of worktrees is running many Claude instances simultaneously. Each gets its own isolated copy of the repo, its own branch, and its own context.

The parallel terminals pattern

Open multiple terminal tabs, each running Claude in a separate worktree:

# Tab 1: Feature work
claude --worktree feature-auth

# Tab 2: Bug investigation
claude --worktree fix-timeout

# Tab 3: Test coverage
claude --worktree add-tests

# Tab 4: Documentation
claude --worktree update-docs

Configure your terminal (iTerm2, Warp, etc.) to notify you when any instance needs input. This lets you supervise 3-5 Claude instances productively.

Shell aliases for quick switching

# In ~/.zshrc or ~/.bashrc
alias cw1='claude --worktree wt-1'
alias cw2='claude --worktree wt-2'
alias cw3='claude --worktree wt-3'

Batch operations

For large-scale tasks like migrations, Claude can fan out work to multiple subagents, each running in its own worktree:

Migrate all 12 API route files from Express to Hono.
Use subagents with worktree isolation — one per route file.
Each subagent should migrate its file, update imports, and run
the tests for that route. Create a PR for each.

Each subagent works independently: makes changes, runs tests, and reports back. Because they’re in separate worktrees, there are no file conflicts.

When parallel execution helps most

• Migrations: convert files from one framework/pattern to another
• Bulk refactors: rename across many modules simultaneously
• Parallel investigation: explore multiple hypotheses about a bug
• Feature + fix: keep feature work going while fixing an urgent issue
• Review + build: review a PR in one worktree while building in another

Copying environment files

Worktrees are fresh checkouts — they do not include gitignored files like .env or .env.local. Add a .worktreeinclude file to your project root listing patterns of gitignored files to auto-copy:

.env
.env.local
config/secrets.json

Only files matching a pattern that are also gitignored get copied. Tracked files are never duplicated.

Tips

• Use --tmux with --worktree to run sessions in the background and check on them later.
• Start with 2-3 parallel instances before scaling to 5+. Context-switching between too many instances reduces the quality of your supervision.
• Worktrees share the same .git directory, so commits made in one are visible from the other after a fetch.
• When you exit a worktree session, Claude auto-cleans worktrees with no changes. If changes exist, you are prompted to keep or remove.
• Add .claude/worktrees/ to your .gitignore to prevent worktree contents from appearing as untracked files.
• For long-running parallel work, name your worktrees descriptively (fix-auth-timeout not wt-1).