Why I Run Claude Code in Git Worktrees (And You Probably Should Too)

For the first month I used Claude Code, I ran it the way I ran every other coding tool: from my repo's root directory, one session at a time. It worked. But every time Claude was halfway through a feature and I needed to pop over to main to fix a typo in production, I'd hit the same wall — stash, checkout, find that Claude's session was now confused about what branch it was on, lose context, swear quietly.

The fix turned out to be a Git feature that's been in the toolbox since 2015 and that I had never used: git worktree.

What git worktree actually does

A worktree is a second (third, tenth) working directory attached to the same .git folder. Different directory, different branch checked out, same repo history. Disk usage is minimal — only the working files duplicate, not the object database.

# from inside your main repo
git worktree add ../myrepo-hotfix main
git worktree add ../myrepo-feature-x -b feature/x

You now have three sibling directories, each on its own branch, each fully usable.

Why this matters for Claude Code

Once you have worktrees, the workflow becomes obvious: one worktree per Claude session.

mkdir -p ~/work/myrepo-worktrees
cd ~/work/myrepo
git worktree add ../myrepo-worktrees/feat-auth -b feat/auth
git worktree add ../myrepo-worktrees/feat-billing -b feat/billing
git worktree add ../myrepo-worktrees/hotfix-prod -b hotfix/prod

# now spin up three Claude sessions in three terminals
cd ~/work/myrepo-worktrees/feat-auth && claude
cd ~/work/myrepo-worktrees/feat-billing && claude
cd ~/work/myrepo-worktrees/hotfix-prod && claude

Each Claude session is rooted in a different directory, on a different branch, with its own file context. They cannot step on each other's edits. The "branch is already checked out at..." error goes away because each worktree owns its branch. And when one agent finishes, merging is a normal git merge — no branch acrobatics needed.

For me this turned "one feature at a time" into "three parallel features all day", and the only thing it cost was 200 MB of duplicated node_modules.

The tmux setup that made it click

I wrap the three sessions in a tmux window so I can glance at all three at once:

tmux new-session -d -s claude-pool
tmux send-keys -t claude-pool 'cd ~/work/myrepo-worktrees/feat-auth && claude' C-m
tmux split-window -h -t claude-pool
tmux send-keys -t claude-pool 'cd ~/work/myrepo-worktrees/feat-billing && claude' C-m
tmux split-window -v -t claude-pool
tmux send-keys -t claude-pool 'cd ~/work/myrepo-worktrees/hotfix-prod && claude' C-m
tmux attach -t claude-pool

Three panes, three agents, zero context collision.

Gotchas

• node_modules: each worktree needs its own. Either eat the disk cost or use pnpm with a shared store.
• .env files: these are gitignored, so they don't follow you into a new worktree. Symlink or copy.
• Hooks: git hooks live in .git/hooks which is shared across worktrees. Test once, runs for all.
• Removing a worktree: never rm -rf the directory. Use git worktree remove <path> so Git's bookkeeping stays consistent, or you'll see worktree is dirty errors later.

When it's overkill

If you only ever run one agent at a time and you're not context-switching across hotfixes, plain branches are fine. Worktrees pay off when parallelism × interruption rate is high — which, with AI agents, it nearly always is.

---

I ended up cataloging every git worktree command, every common error, and the setups for Cursor / Codex / OpenCode too over at gitworktree.org — the Claude Code + worktree guide is the one I refer back to most.

If you've got your own worktree tricks for AI agents, drop them in the comments — always looking for the next 10% of speedup.