Git Worktrees: Run Multiple Claude Sessions Without Conflicts

The Collision Problem

Open two terminals. Start Claude in both. Ask one to refactor your authentication module while the other adds a new API endpoint. Within minutes, both sessions are editing src/auth.ts — and one of them just silently overwrote what the other wrote.

This is the collision problem. It's not a Claude limitation — it's a filesystem limitation. Two processes sharing the same working directory will eventually step on each other. The standard solution in git is worktrees, and Claude Code has first-class support for them.

What a Git Worktree Actually Is

A git worktree is a separate working directory attached to the same repository. Each worktree has its own branch checked out and its own file state, but they all share the same .git folder, object store, and history. Creating a worktree costs almost nothing — it's not a clone, it's an additional checkout.

The practical result: you can have /projects/myapp on main, /projects/myapp/.claude/worktrees/feature-auth on feature-auth, and /projects/myapp/.claude/worktrees/bugfix-123 on bugfix-123, all at the same time, each with completely independent file states. Claude sessions in each worktree see only their own files and never interfere with each other.

The --worktree Flag

Claude Code's --worktree flag (also -w) creates an isolated worktree and starts Claude inside it in a single command:

claude --worktree feature-auth

This creates a new worktree at .claude/worktrees/feature-auth/ inside your repository root, on a new branch named worktree-feature-auth, branching from origin/HEAD (your repository's default branch). Claude starts with that worktree as its working directory.

Open another terminal and run a second session on a completely separate task:

claude --worktree bugfix-login

Now you have two independent Claude sessions running in parallel, each on its own branch, each with its own file state, with zero risk of collision. Neither session knows the other exists.

If you omit the name, Claude generates one automatically:

claude --worktree

Add .claude/worktrees/ to your .gitignore so worktree contents don't appear as untracked files in your main checkout:

# .gitignore
.claude/worktrees/

Copying Your Local Config into Worktrees

A worktree is a fresh checkout, which means gitignored files from your main directory — .env, .env.local, API keys, local database config — are not present. Claude sessions in the worktree won't have the credentials they need to run your app.

Solve this with a .worktreeinclude file in your project root. It uses .gitignore syntax, and any gitignored file that matches a pattern is copied automatically into each new worktree Claude creates:

# .worktreeinclude
.env
.env.local
.env.development
config/secrets.json

Only files that are both gitignored and match a pattern in .worktreeinclude are copied. Tracked files are never duplicated. This file is safe to commit — it's just a list of patterns, not the secrets themselves.

How Cleanup Works

When you exit a worktree session, Claude Code handles cleanup based on what happened during the session:

• No changes made — the worktree and its branch are removed automatically. Nothing is left behind.
• Changes or commits exist — Claude prompts you to keep or remove the worktree. Keeping it preserves the directory and branch so you can return to it. Removing it deletes the directory and branch, discarding all uncommitted changes and any local-only commits.
• Non-interactive runs (-p flag) — worktrees are not cleaned up automatically since there is no interactive exit prompt. Remove them manually with git worktree remove.

You can also manage worktrees directly with git:

# List all worktrees (shows path and branch for each)
git worktree list

# Manually remove a worktree
git worktree remove .claude/worktrees/feature-auth

# Create a worktree from an existing branch (no --worktree flag)
git worktree add ../myapp-bugfix bugfix-123

The Parallel Development Pattern in Practice

Here is what a productive multi-session workday looks like with worktrees. You have three things to do: a feature, a bug fix, and a code review.

Terminal 1 — Feature work:

claude --worktree feature-payments

You: "Implement the Stripe webhook handler in src/webhooks/stripe.ts. The handler needs to verify the signature, parse the event type, and update the orders table."

Claude builds the feature on the worktree-feature-payments branch while you move on.

Terminal 2 — Bug fix:

claude --worktree bugfix-session-timeout

You: "Users report they get logged out after 15 minutes even when active. The session refresh logic is in src/auth/session.ts. Find the bug and fix it with a test."

This session works independently in its own branch. It has no idea the payments work is happening.

Terminal 3 — Code review (no worktree needed, read-only):

claude --permission-mode plan

You: "Review PR #247. Focus on security implications of the new file upload handler."

Three things in parallel. No collisions. Each session operates as if it's the only one running.

As of mid-2026, teams commonly run 4–8 concurrent worktrees per developer reliably. The practical bottleneck is usually code review bandwidth, not Claude's ability to work in parallel.

When Not to Use Worktrees

Worktrees add overhead — a new branch, a new directory, a cleanup step. Skip them when tasks are small, sequential, or tightly coupled. If task B depends on task A's output, they should run in the same session. If a change is trivial (a one-line fix), the branch overhead isn't worth it. Use worktrees when tasks are genuinely independent and big enough that parallel execution saves real time.