Running two Claude Code sessions on the same repository at the same time is a recipe for merge conflicts, lost work, and confusing diffs. Both sessions read and write the same files. One session’s changes blow up the other’s assumptions mid-task.
Git worktrees solve this. Each Claude session gets its own working directory checked out to its own branch. They share the same repository history, but the files on disk are completely isolated. No conflicts, no interference, no stepping on each other.
Claude Code has native worktree support built in, and once you understand how it works, parallel AI development becomes genuinely practical — not just theoretically possible.
What Git Worktrees Actually Are
A standard git clone gives you one working tree: one directory, one checked-out branch at a time. To work on a second branch simultaneously, you either stash and switch (losing your place) or clone the whole repo again (wasting disk space and losing the shared history connection).
Git worktrees give you multiple working directories, all backed by a single .git directory. You can have main checked out in ~/project, feature/auth checked out in ~/project-auth, and fix/login-bug checked out in ~/project-login-fix — all as separate directories, all pointing at the same repository.
Changes committed in any worktree are immediately visible to the others. There is no sync step.
# Create a worktree manually
git worktree add ../project-feature feature/new-api
# List all active worktrees
git worktree list
# Remove a worktree when done
git worktree remove ../project-featureClaude Code automates all of this for you.
The —worktree Flag
The simplest way to use worktrees with Claude Code is the --worktree flag (short form: -w):
claude --worktree feature/authThis does three things in sequence:
- Creates a new branch named
feature/authfrom your current HEAD - Creates a new worktree directory for that branch (Claude places it adjacent to your main repo by default)
- Starts Claude Code inside that worktree directory
When you exit the session, Claude’s cleanup behavior depends on what happened:
- No changes made: The worktree and its branch are deleted automatically. Clean slate.
- Changes committed: Claude prompts you to keep or remove the worktree. If you keep it, the directory and branch persist for later.
- Uncommitted changes: Claude warns you before cleaning up.
The cleanup behavior is intentional. If a worktree session produces nothing useful, it should leave no trace.
Subagent Isolation with Worktrees
Worktrees become especially valuable when using Claude Code’s subagent system. When multiple subagents work in parallel on the same repository, they need isolation or they will conflict at the file level.
You enable worktree isolation per-subagent in AGENTS.md:
# agents
## feature-builder
description: Implements new features on isolated branches. Writes code, runs tests, commits changes.
tools: read, write, bash, edit
isolation: worktree
model: claude-sonnet-4-6
## refactor-worker
description: Refactors existing code for readability and performance. Works on isolated branches.
tools: read, write, bash, edit
isolation: worktree
model: claude-sonnet-4-6With isolation: worktree, each subagent invocation automatically gets its own worktree. Two feature-builder subagents running simultaneously will not interfere with each other. When a subagent finishes with no changes, its worktree is cleaned up automatically.
A Real Parallel Workflow
Here is how this looks in practice. Say you are doing a large refactor and want to parallelize the work:
Step 1: Launch parallel research subagents
Task: I need to refactor our authentication module.
Use three parallel subagents to:
1. Analyze the current auth code and list all dependencies
2. Research best practices for our stack (Node.js + JWT)
3. Check if there are any security issues in the current implementation
Use isolation: worktree for all three.Each subagent gets its own worktree, reads what it needs, returns a summary. Your main context window stays clean.
Step 2: Plan based on results
The main agent synthesizes the three summaries into a migration plan. This happens in your main session — no worktrees needed, just thinking.
Step 3: Execute in parallel
Task: Execute the auth refactor plan.
Spawn two parallel implementation subagents:
1. Refactor the token generation module (feature/auth-tokens)
2. Refactor the session management module (feature/auth-sessions)
Both should use worktree isolation and commit their changes.Two branches, two worktrees, two Claude sessions — all running simultaneously. When they finish, you review and merge.
Running Multiple Terminal Sessions Manually
You do not have to use subagents. The --worktree flag works just as well for manual parallel sessions across multiple terminals:
Terminal 1:
cd ~/project
claude --worktree feature/new-dashboard
# Claude is now working in ~/project-new-dashboard on branch feature/new-dashboardTerminal 2:
cd ~/project
claude --worktree fix/broken-api
# Claude is now working in ~/project-fix-broken-api on branch fix/broken-apiBoth sessions run simultaneously. Both can read, write, and commit without touching each other’s files. Your main ~/project directory with main checked out is untouched.
Worktree + CLAUDE.md Behavior
One important detail: CLAUDE.md files in worktrees follow the same directory-hierarchy rules as in a normal checkout. If your CLAUDE.md is at the repository root, it will be present in every worktree because they all share the same repo. Project-level instructions apply everywhere.
If you want subagent-specific instructions, put them in AGENTS.md or in a subdirectory-level CLAUDE.md in the relevant package.
When Worktrees Are Worth It
Worktrees add a small amount of overhead — an extra directory, a managed branch, slightly more complex cleanup. They pay for themselves when:
- Tasks take more than a few minutes: Short tasks do not benefit enough from parallelism to justify the setup.
- Tasks touch different parts of the codebase: Parallel sessions on the same files still produce conflicts.
- You want reviewable, isolated history: Each worktree commits to its own branch, giving you a clean diff per task.
- You run subagents that modify files: Any subagent doing writes benefits from isolation.
They are overkill for quick one-file edits or anything where sequential execution is fast enough.
Worktrees Are Not Sandboxes
One thing worktrees do not provide: process isolation. All Claude Code sessions on your machine share the same environment variables, the same database if you have one running locally, and the same network. A subagent running in a worktree can still hit your local dev server, write to a shared database, or call external APIs.
For true isolation (separate databases, network rules, etc.), you need containers or VMs. Worktrees solve the file conflict problem, not the environment conflict problem.
Common Mistakes
Naming worktree branches the same as existing branches. If feature/auth already exists, claude --worktree feature/auth will error. Use unique names or delete the old branch first.
Forgetting to clean up. If you do not let Claude’s automatic cleanup run (e.g., you kill the session mid-task), worktrees and branches accumulate. Run git worktree list and git worktree remove periodically.
Trying to checkout the same branch in two worktrees. Git prevents this. Each branch can only be checked out in one worktree at a time.
Running subagents without worktree isolation on file-writing tasks. This is the most common source of conflicts. If subagents write files and you do not use isolation: worktree, they will step on each other.
The Bigger Picture
Worktrees are how you make Claude Code scale beyond single-task sequential use. The combination of worktrees + subagents + parallel execution is what lets you throw a complex, multi-part project at Claude and get coherent results back — because each part ran independently, without polluting the others.
The workflow is not complicated once you have seen it once: flag or AGENTS.md entry to enable isolation, let Claude manage the branch lifecycle, review and merge the outputs. The git plumbing does the hard part.