Guides

Why parallel sessions break

A single checkout holds one mutable set of files, which is fine while one task is in flight. The trouble starts when two Claude Code sessions share the same directory: each one plans from the files it sees and writes back into the same tree, so a refactor in one session can land under the other before it knows anything has moved. A formatter pass or a lockfile update can rewrite files the other conversation was still depending on, and the agent reading those files next has no way to tell that the ground shifted under it.

The failure rarely arrives as a merge conflict. By the time you see one, both agents have been working against silent drift for a while, each reasoning from a snapshot of the code the other has long since edited. Branches don't rescue you here. A branch is a pointer at a commit, and the files on disk only ever exist in one configuration at a time. To move between tasks in a single checkout you stash, switch branches, restore whatever local state you can, and hope the conversation you paused still recognizes what's now sitting in src/ when you come back to it.

What a worktree is

A Git worktree is a second checkout of the same repository. The new working directory shares its history and object database with the original, but the files, the HEAD, and the index are all its own, so you can keep one branch live in my-repo/ and another in my-repo-feature-auth/ at the same time without either directory knowing the other one exists.

my-repomain

src/auth.ts

src/client.ts

src/cache.ts

feature-auth

src/auth.ts

src/client.ts

src/cache.ts

claude session

bugfix-timeout

src/auth.ts

src/client.ts

src/cache.ts

claude session

experiment-cache

src/auth.ts

src/client.ts

src/cache.ts

claude session

same files · independent edits · no collisions

For Claude Code, the locality is what matters. Each session is editing a filesystem nobody else is touching, so two agents working in parallel can't overwrite each other's in-flight work. Branches can still conflict at merge time, but a diff against another diff is what merge tools were built to handle. Worktrees stop the other failure: a running session trashing a file that another session is still editing.

Claude Code workflow

You don't need to run git worktree add by hand for the common case. Start a Claude session with the worktree flag:

Local terminal

$claude --worktree feature-auth

That creates a new worktree at .claude/worktrees/feature-auth/, opens a branch named worktree-feature-auth off your default branch, and drops you into a Claude session inside the new directory. The short form is claude -w feature-auth, and if you leave the name off Claude picks one for you.

To run two tasks at once, open a second terminal and start another worktree session in the same repository. Each session brings a fresh working tree and a fresh conversation, isolated from the others on disk.

Add .claude/worktrees/ to your .gitignore once. Otherwise every new worktree directory shows up as untracked files in your main checkout.

Isolation handles the filesystem. Defining the task is still your job, so each session should open with a prompt that pins down the scope:

A good first prompt inside a worktree

You are in an isolated Claude Code worktree. Task: Implement the retry behavior described in docs/retry-plan.md. Scope: - Change only the client package and its tests. - Do not perform broad refactors. - Do not update unrelated snapshots, generated files, or lockfiles unless necessary. - Do not commit unless I explicitly ask. Validation: - Inspect git status before editing. - Run the relevant tests before summarizing. - If setup is missing, tell me exactly what failed and why. Final report: - Changed files - Tests run and results - Remaining risks - Anything you intentionally left out

A cheaper way to run sessions in parallel will not save you from vague tasks. Spell out the scope, the checks, and the report you want back.

Good use cases

Use worktrees when tasks are genuinely separable. The goal is isolation when multiple things need to be in flight, not running the most sessions.

Urgent interruption

hotfix

You are halfway through a refactor and a production issue arrives. The refactor stays in place and the hotfix gets a clean branch and directory. No stash, no branch mutation.

claude --worktree hotfix-prod-timeout

Parallel independent tasks

parallel

Tasks that touch different modules, packages, or test suites can run simultaneously. Works well when the tasks are genuinely separable.

claude --worktree feature-new-metric claude --worktree bugfix-null-response

Comparative implementations

experiment

Give two isolated sessions the same spec and compare diffs, test results, and maintainability. Keep the better one or synthesize a third.

claude --worktree experiment-parser-a claude --worktree experiment-parser-b

Risky migrations

migration

Large mechanical changes get space to make invasive edits without polluting the main checkout. That doesn't replace review. It lowers the cost of the experiment.

claude --worktree migration-pydantic-v2

Where worktrees do not help

Coupled decisions still need to be serialized. If session A refactors the auth middleware, session B changes its behavior, and session C regenerates the auth client, three sessions are editing one design surface. You can use separate worktrees to investigate, but one person has to make the call and merge in order.

Run independent execution in parallel. Keep shared judgment in one head.

Sharp edges

Worktrees handle file and branch isolation. Runtime concurrency is your problem.

Manual Git commands

claude --worktree covers the common case, but the underlying Git commands matter when you want an existing branch, a specific base branch, a worktree outside .claude/, or a custom naming convention.

Create a new branch in a new worktree

Local terminal

$git worktree add ../my-repo-feature-auth -b feature-auth main

Create a worktree from an existing branch

Local terminal

$git worktree add ../my-repo-bugfix bugfix-123

List all worktrees

Local terminal

$git worktree list

Remove a worktree

Local terminal

$git worktree remove ../my-repo-feature-auth

Prune stale metadata after a manual deletion

Local terminal

$git worktree prune

Merging and cleanup

A worktree's life ends with a merge and a cleanup. The merge itself is ordinary Git, whatever flow you already use, whether that's pushing the branch to open a PR or merging it locally from your main checkout.

Local terminal

$cd ~/my-repo
git merge worktree-feature-auth

When the merge produces conflicts, a Claude Code session running in the main checkout is the right place to resolve them. It can read both sides, propose a resolution, run the relevant tests, and commit when the result looks clean. The worktree itself is no longer needed at that point. Its branch already carries the work.

Once the work is in, the worktree directory and the branch can both come down:

Local terminal

$git worktree remove .claude/worktrees/feature-auth
git branch -d worktree-feature-auth

If you exit a Claude Code worktree session that has nothing uncommitted, Claude offers to remove the directory and branch on the way out. With committed work it asks first, so cleanup is opt-in rather than automatic. After deleting a worktree directory by hand, run git worktree prune to clear out the stale metadata Git keeps about it.

Worktrees remove one bad assumption from your day: that several tasks can share one mutable checkout. You still owe the work task decomposition, review, tests, and merge discipline. Worktrees keep independent work from tangling before you get to any of that.

Local terminal

$claude --worktree feature-your-thing

Parallel Claude Code with Git Worktrees