Worktrees and parallel isolation

Everything Claude Code offers for working in parallel — agent teams, agent view, multiple sessions — runs into the same wall: two agents editing one working directory will conflict.

A git worktree is the answer. Each session gets its own checkout of the same repository, on its own branch, in its own directory.

Why Anthropic documents this rather than assuming you know

Worktrees are an old git feature that most developers have never needed. Branch switching was always enough, because you were one person doing one thing.

Parallelism breaks that assumption. The moment three sessions are working simultaneously, “check out a different branch” is not available — they all need their files at once.

What it does not solve

• Merge conflicts. Worktrees keep the work apart; combining it is still your problem, or an agent team’s.
• Shared state outside the repository. One database, one dev server, one port. Isolation stops at the filesystem boundary.
• Usage. Three sessions consume three sessions’ worth of your plan.
• Security. A worktree is not a sandbox. For that, see sandbox environments and permissions.

When you do not need one

If your parallelism is subagents rather than sessions, you do not need worktrees. Subagents run inside one session against one working directory, and the lead agent serialises the edits. The distinction is in subagents vs agent teams.