There is a moment, usually around your third Claude Code session, when the fantasy of parallel agents collides with the reality of a single human attention span. You opened a second terminal because Claude was thinking and you had nothing to do. You opened a third because the second one was thinking too. Now there are three streams of edits happening across three branches, and the question is no longer “can I run parallel sessions” — it is “did I just spend the next forty minutes reviewing diffs I could have written myself in twenty.”
Git worktrees plus claude --worktree make multi-session work physically safe. They do not make it economical. The pattern below is the one I have settled on after running everything from two-up to a foolish eight-up. The short version: two is the default, four is the ceiling, and the ceiling is set by review bandwidth, not by Claude.
What worktrees actually fix
A git worktree is a second working directory attached to the same repository — its own branch, its own files on disk, sharing history and remote with the main checkout. Without them, running two Claude Code sessions against one clone is asking for a merge conflict you will not see coming. One session edits src/auth.ts while the other is mid-refactor of the same file; the second write wins; your tests pass; the first session’s logic is gone.
The claude --worktree my-feature flag creates the worktree for you under .claude/worktrees/, checks out a new branch, and scopes the entire session to that directory. Edits in one -w session cannot touch files in another. That is the entire safety guarantee, and it is the only one you need to run multiple sessions in good conscience.
The catch nobody mentions in the launch posts: a worktree is a fresh checkout. Your .env, your .env.local, your node_modules, your virtualenv — none of it carries over. The first session in a new worktree spends ten minutes failing in confusing ways because the environment is empty.
The fix is a .worktreeinclude file at the project root, gitignore-syntax. Files that match a pattern and are gitignored are copied into the new worktree at creation. Tracked files are never duplicated. A two-line .worktreeinclude with .env* and .env.local is usually enough to get past the first failure mode. Dependencies are a separate problem — most teams either symlink node_modules or run install fresh per worktree depending on how strict their lockfile discipline is.
The two-session pattern
This is the default and the one that pays its setup cost on the first week. The shape:
- Foreground session. What you are actively working on. You read every diff. You answer questions. You
/planthe multi-file changes. - Background session, separate worktree. A bounded task you can describe in one paragraph and verify in one diff. Documentation update, refactor of a single module, dependency bump and test run, generated-API-client rebuild. You start it, switch back to the foreground, and check on it when it finishes.
The economics are clean. The background task would have cost you context-switching time anyway — opening it, loading the problem into your head, doing the work, putting it down. Instead you describe it once, let Claude run, and review one diff at the end. Two sessions, one human, real time saved.
The discipline that makes this work: the background task is always something you would be comfortable letting a junior engineer commit without a meeting. If you would not, it is not a background task — it belongs in the foreground.
The four-session ceiling
Above two, the gains compress fast. Three is fine if the third session is something near-trivial — a script, a one-off data migration, a README pass. Four is the practical ceiling and only on days where the work decomposes that cleanly.
The reason is review, not Claude. Each session produces a diff. Diffs are not free to read. A senior engineer in flow reads code at maybe two hundred lines per minute with comprehension; a five-hundred-line diff from a Claude session costs at least two minutes of focused attention, often five if the change is subtle. Four sessions producing four diffs in the same ten-minute window means twenty minutes of review queued up — and you cannot review them in parallel.
The pattern that breaks first is the one where you stop reading the diffs carefully because there are too many of them. That is the failure mode worth naming. The point of running parallel sessions is to compress wall-clock time. The point is not to compress review time, because review time is the part that actually catches the bug.
If you find yourself merging diffs you have only skimmed, you are running too many sessions. Drop back to two.
When the pattern earns its keep
Two scenarios where multi-session worktrees clearly beat the single-session default:
The refactor-and-feature split. You are in the middle of building a feature. Halfway through you notice the underlying module needs a refactor before the feature can be finished cleanly. In the single-session model you stop the feature, do the refactor, and restart the feature with the refactored module in your head. In the worktree model you fork the refactor into its own worktree, keep the feature work going in the main worktree against the unrefactored code, and rebase the feature onto the refactor once it lands. You do not lose your place on the feature work.
The long-tail cleanup pass. A list of twelve small chores nobody wants to do in series: dependency updates, doc fixes, lint cleanups, deprecated-API migrations. Worktree per chore, three at a time, Stop hooks running the test suite, you reviewing as each finishes. The single-session alternative is a forty-five-minute slog. The parallel version is fifteen minutes of dispatch and review.
The scenario where it does not earn its keep: novel design work where the right answer requires you to hold the whole problem in your head. Splitting attention across two unfamiliar design problems means doing both of them worse than you would have done either of them alone.
The setup that makes it usable
If you have not done this before, this is the order:
First, write a .worktreeinclude with at minimum .env* and any other untracked config your project needs. Test it by running claude --worktree test-include and verifying your env loads. Delete the worktree with git worktree remove .claude/worktrees/test-include once verified.
Second, add a WorktreeCreate hook if your project has any setup beyond env files — installing dependencies, running migrations, building a generated client. The hook fires when claude --worktree is invoked, before the session starts, so any setup you script runs against a clean checkout every time. The hook output prints the worktree path on stdout and Claude opens there.
Third, establish a worktree naming convention before you have ten of them sitting around. feature/auth-rewrite, chore/dep-bump-react, fix/oauth-callback — anything that tells you in a year what the worktree was for. The default .claude/worktrees/ directory fills up faster than you expect.
Fourth, set a personal ceiling. Mine is four. Yours might be three. The ceiling is whatever number of diffs you can review carefully in the time the sessions take to run. Write that number down somewhere you will see it when you are about to open a fifth terminal.
What this pattern is not
It is not parallelization in the engineering sense. The sessions are not coordinating. They are independent. Tasks with real dependencies — “refactor module A, then build feature B against it” — belong in one session, sequenced, with a /plan step in the middle. Splitting them across worktrees just means you spend extra time rebasing.
It is also not a productivity hack in the autonomous-agent sense. Claude Code’s subagents and skills are the right tools when you want the same session to delegate work to context-isolated children. Worktrees are for when you want to run independent sessions in parallel because the tasks are independent and you can review the outputs separately. Different layer, different problem.
The worktree pattern works because git worktrees were already the right primitive for parallel feature work before Claude Code existed. claude --worktree is the convenience flag that makes the primitive cheap. The discipline — two by default, four at the ceiling, never more diffs than you will actually read — is the part that turns convenience into useful workflow.
Leave a Reply