Claude Code Worktrees

Problem: A Claude Code session is humming along on a feature branch, and a production bug lands on your desk. Your choices are bad: stash and lose the working state, start a second terminal and watch both sessions fight over the same files, or bail out of the session entirely.

Quick Win: Open a second Claude Code session inside its own worktree:

claude --worktree bugfix-123

A fresh working directory lands at .claude/worktrees/bugfix-123/ on its own branch, worktree-bugfix-123. The first session is left alone. Nothing gets stashed. Nothing collides. Two Claude sessions run side by side, and neither one knows the other exists.

If you are deciding between agent patterns, keep the boundary simple: read Agent Fundamentals when you need subagents, slash commands, or lightweight specialization inside one session. Read this page when the real problem is filesystem isolation, separate branches, and parallel work that must not touch the same checkout. For orchestration shapes on top of that isolation, read Agent Patterns.

Why Worktrees Change Everything

Anyone who has pushed Claude Code with sub-agents or background agents has hit the ceiling. Two agents start editing the same file at the same time. One rewrites src/auth.ts while the other is halfway through the same module. What comes back is half-applied changes, a merge mess, or something worse.

Worktrees fix this at the filesystem. Each one is a separate checkout of the repo with its own branch, directory, and index. Worktree support became first-class in Claude Code v2.1.50, which covers creating, managing, and cleaning them up from the CLI, the Desktop app, and even custom agents.

The CLI: --worktree Flag

Launching Claude Code with the --worktree flag is the fastest path in.

Named worktrees

# Start Claude in a named worktree
claude --worktree feature-auth
 
# Creates:
# .claude/worktrees/feature-auth/  (working directory)
# Branch: worktree-feature-auth    (branched from default remote branch)

Every worktree drops into its own folder under .claude/worktrees/ on a dedicated branch. Spin up as many as your disk will put up with.

Auto-named worktrees

# Let Claude generate a name
claude --worktree

Handy for throwaway runs where the branch name really doesn't matter.

Multiple parallel sessions

# Terminal 1: working on auth
claude --worktree feature-auth
 
# Terminal 2: fixing a bug
claude --worktree bugfix-123
 
# Terminal 3: exploring a refactor
claude --worktree experiment-new-router

Three sessions. Three branches. Zero conflicts. Each one can read the full git history, but the files under each session live in their own tree.

Mid-session worktree creation

The flag isn't required at launch. You can ask inside any live session:

You: work in a worktree
Claude: I'll create an isolated worktree for this session...

Claude sets up the worktree and moves the session into it. This rescues you when it turns out, partway through a conversation, that the work should have been isolated from the start.

Desktop App: Automatic Isolation

The Claude Code Desktop app goes one step further. Every new session gets its own worktree by default.

By default, those worktrees land in .claude/worktrees/. Desktop Settings lets you change the path and set a branch prefix so Claude-made branches stay grouped. Done with a session? Hit the archive icon and the worktree plus its branch go away.

So every Desktop session is safe out of the box. Sessions don't write over each other, and you don't have to coordinate them.

Subagent Worktree Isolation

This is where the feature pays off. Each sub-agent Claude spawns for a distributed task can get its own worktree.

Asking Claude to isolate agents

Easiest version:

You: Use worktrees for your agents when doing this refactor

Every sub-agent lands in its own worktree. A worktree that finishes with no edits is thrown away on its own. A worktree that actually changed something sticks around for you to read.

Why this matters for parallel execution

Without isolation, parallel sub-agents can only read files or write inside non-overlapping paths. That's a weak boundary. The moment one agent strays into another's lane, you get silent conflicts.

With isolation, each agent sees the whole codebase by itself. Agent A can take a shot at src/auth.ts one way while Agent B takes a shot at the same file the other way. You open both branches and pick the better one (or stitch pieces of both together).

This really shines on batched migrations. You have 50 files to move from one API to another? Start five agents, ten files each, every one in its own worktree. They work in parallel and nobody trips over anybody. The built-in /batch command rides this same rail, launching worktree-isolated agents from a single prompt to run migrations across a codebase.

Custom Agents with Built-In Isolation

Custom agents under .claude/agents/ can be pinned to always use a worktree:

---
name: refactor-agent
description: Agent that performs isolated refactoring work
isolation: worktree
---
You are a refactoring specialist. Analyze the target code,
plan the refactor, and implement changes.

isolation: worktree in the frontmatter tells Claude to make a fresh worktree every time this agent runs. The agent works in full isolation, and an empty worktree deletes itself when the run ends.

Non-Git VCS Support

Teams on Mercurial, Perforce, or SVN aren't locked out. Worktree mode still runs, using custom hooks. Register WorktreeCreate and WorktreeRemove hooks in your settings so your VCS's own isolation logic replaces the default git behavior.

With those hooks in place, the --worktree flag and in-session worktree requests route through your hooks instead of shelling out to git. Everything else about the flow is unchanged.

Three Worktree Patterns Worth Stealing

Most teams understand the basic idea once they see it. What they usually need next is a working pattern they can copy.

1. Hotfix without blowing up feature work

You are halfway through a feature branch when a production auth bug lands.

# Keep your current feature session alive
claude

# Open a second isolated bugfix session
claude --worktree hotfix-auth-timeout

Now the hotfix can ship cleanly while the feature session keeps its state, todos, and conversation history. This is the simplest high-value use of worktrees and the one most teams adopt first.

2. Competing implementations for the same risky refactor

Suppose a routing refactor has two possible shapes. One keeps the current API surface and moves internals. The other simplifies the external API too.

Run both:

claude --worktree router-safe-path
claude --worktree router-clean-slate

Both sessions can touch the same files because they are not sharing a checkout. Review both branches after the fact and keep the stronger design. This is far better than trying to force one agent to reason through both paths in a single context.

3. Batch migrations with isolated subagents

Say you need to replace one logging API in 80 files. You do not want five agents editing the same checkout.

Ask for the split explicitly:

You: Use worktrees for agents. Split this migration into 5 batches of files.

That gives each worker:

• a full repo view
• a narrow file batch
• an isolated branch
• a reviewable result

This is where worktrees stop being a convenience feature and start behaving like actual parallel infrastructure.

Small Rules That Keep Worktrees Sane

The mechanics are easy. The team habits are what keep them useful:

• Name worktrees after the outcome, not the ticket alone
• Delete empty or abandoned worktrees quickly
• Use one worktree per active line of thought
• Keep branch prefixes consistent so cleanup is obvious
• Review diffs before merging between worktrees just like any other branch

If worktrees start feeling messy, it is usually not because there are too many of them. It is because nobody can tell which ones are disposable and which ones matter.

Cleanup and Housekeeping

How a worktree gets cleaned up depends on whether anything actually changed inside it:

• No changes: The worktree and its branch are automatically removed when the session ends
• Changes exist: Claude prompts you to keep or remove the worktree

Keep worktree folders out of version control with a line in .gitignore:

echo ".claude/worktrees/" >> .gitignore

Worktrees piling up? Regular git commands will list and prune them:

git worktree list
git worktree prune

When to Use Worktrees

Rule of thumb: any time you'd reach for a separate branch to dodge conflicts, reach for a worktree instead. You get the branch, and you get a separate working directory with it.

Remember: Worktrees turn Claude Code from one thread into a parallel dev environment. Launch isolated sessions. Dispatch isolated agents. Merge the winners when you're ready.