Worktrees: running sessions that cannot step on each other

Two Claude Code sessions in the same directory edit the same files, and the moment both touch config.ts you have a race you did not design. Subagents and parallel work raise this constantly: the value is doing two things at once, and the hazard is that "at once" means "over each other." Worktrees are git's answer, and Claude Code builds on it.

What a worktree actually is

Straight from the documentation: "A git worktree is a separate working directory with its own files and branch, sharing the same repository history and remote as your main checkout". One repository, one history, several working copies — each on its own branch, each isolated on disk.

The payoff for agents is one sentence: "Running each Claude Code session in its own worktree means edits in one session never touch files in another, so one session can build a feature while a second fixes a bug". The isolation is physical, not a matter of the model being careful. That is the whole point: "Worktrees are one of several ways to run Claude in parallel", and the one that removes file collisions by construction rather than by vigilance — which is the same reason hooks beat asking nicely.

One prerequisite: "Worktrees require a git repository; for other version control systems, configure hooks to replace the git logic".

Starting one, and the trap waiting inside it

claude --worktree <name> (or -w) creates an isolated worktree under .claude/worktrees/<name>/ on a branch worktree-<name>, and starts the session there. Run it again with a different name in another terminal for a second isolated session. In the desktop app it is automatic — "every new session gets its own worktree automatically".

The trap is that the isolation is complete, including from your setup. "A worktree is a fresh checkout, so initialize your development environment there": dependencies are not installed, and — the part that bites — your .env, local config and secrets are not present, because they were never committed and a fresh checkout only has what git tracks. The documented fix is a .worktreeinclude file listing the untracked paths to copy into each new worktree (env files, a secrets config). Without it, the session in the worktree fails in ways that look like broken code and are actually a missing environment.

Two housekeeping notes the docs are firm about: add .claude/worktrees/ to your .gitignore so "worktree contents don't appear as untracked files in your main checkout", and remember the branches and directories persist until you clean them up.

Subagents, and the one that survives conflict

Worktrees compose with subagents: "Subagents can run in their own worktrees so parallel edits don't conflict". This is what makes a genuine fan-out safe — three subagents each editing the same files in one directory is a corruption waiting to happen; three subagents in three worktrees is three independent branches you merge on your terms.

The boundary that needs your eyes

Moving between worktrees inside the project is free. Leaving the project is not, and the docs guard it deliberately: when Claude enters a path outside the repository's .claude/worktrees/ directory, "Claude Code asks for your approval first, because the move takes the session's working directory, write access, and project configuration such as CLAUDE.md and settings to that location".

Read that as a permissions event. The session's write access and its governing config travel with it, so an approved move out of the tree is an approved change to what the agent can touch and which rules constrain it. Treat the prompt as the security decision it is, not a dialog to dismiss.

What goes wrong

The empty environment. The worktree session cannot find .env or the installed dependencies, and the failure reads like a code bug. .worktreeinclude plus a setup step is the fix, done once.

Untracked worktrees in the main checkout. Skipping the .gitignore line leaves .claude/worktrees/ showing as a wall of untracked files, and a broad git add can drag a whole worktree into a commit.

Parallel sessions in one directory anyway. Two agents, one checkout, because the worktree felt like ceremony. The collision arrives on the first shared file, and it is worse than the setup you skipped.

Secrets copied too widely. .worktreeinclude is convenient, so it grows. Every path it copies is now duplicated across every worktree — fine for a dev .env, a problem for anything you would not want in several places at once.

Dismissing the leave-the-tree prompt. It reads as a routine approval, but it hands your write access and CLAUDE.md to a new location. It is the one worktree prompt that is actually a security decision.

How to check it worked

Start two worktree sessions and have each change the same file, then diff: the edits should sit on two branches with no interference, which is the property you came for. Then confirm the environment came across — run the test suite inside a fresh worktree. Green means .worktreeinclude and setup are right; a wall of "cannot find module" or "missing key" means the isolation worked and took your setup with it, which is the whole lesson in one error message.