Git worktrees — Parallel sessions

What it does

A git worktree is a separate working directory attached to the same repository. Instead of git checkout branch-b (which rewrites your current directory), you create a new directory that checks out branch-b independently. Both directories coexist — you can compile, test, or run Claude Code sessions in each without affecting the other. Internally, git still tracks them as one repo; changes to one don't show up in another until you push and pull explicitly.

git worktree add ../branch-b-work branch-b

This creates a sibling directory with branch-b checked out. Your original directory stays on its current branch untouched.

When to use it

In Claude Code: Worktrees shine when you want to run parallel, isolated sessions without constant branch switching overhead or context contamination.

Real scenarios:

• Code review + implementation in parallel: Review a PR in one worktree (/repo-review) while writing a feature in another (/repo-feature). Each has its own running dev server, test suite, and Claude Code session. No stepping on each other.
• Testing multiple branches: Checkout main in one worktree, experimental-refactor in another, and run tests in both to compare performance or behaviour without context switches.
• Avoiding interruption overhead: When Claude Code is mid-build or running tests, spawn a new worktree for a quick bug fix on a different branch instead of canceling the in-progress work.
• Snapshot verification: Keep a worktree pinned to a known-good commit for regression testing while your main worktree drifts forward.

The workflow feels like having multiple copies of the repo without the disk duplication. Git handles the bookkeeping; you just navigate to the directory you want.

Try it yourself

Create a worktree for a feature branch and verify that changes in one don't appear in another — check git status in both directories to confirm they're independent. Then delete the worktree cleanly with git worktree remove and watch it disappear from the list.

Gotchas

Disk bloat quickly. Each worktree duplicates the working directory but shares the .git folder. On a large monorepo with node_modules, you'll burn disk fast. Use .gitignored directories sparingly or prune aggressively.

Never delete the main worktree by hand. If you manually rm -rf your original directory instead of using git worktree remove, the repo gets confused. Always use the tool to clean up.

Branch deletion trips you up. If you delete a branch on GitHub and forget you have a worktree checked out to it locally, the worktree still exists but is orphaned. Use git worktree prune periodically to clean these up.

Stale refs after rebases. If someone force-pushes a branch, worktrees checked out to it won't auto-update. You'll need to manually fetch and rebase.

Performance overhead. Each worktree rebuilds node_modules, compiled assets, etc. on first use. If you spawn many worktrees, first builds are slow. Consider sharing build outputs via symlinks or environment variables for large projects.