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.

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.

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.