Worktree Isolation in Claude Code: Parallel Work Without Conflicts

Git worktrees give you multiple independent working directories from a single repository — each on its own branch, with no shared files. Claude Code uses this to run parallel subagents on completely isolated checkouts, so two tasks can modify different parts of the same codebase simultaneously without stepping on each other. For the full Claude Code feature overview, see the Claude Code Complete Guide.

What Git Worktrees Are

A standard git repository has one working directory tied to one branch at a time. To work on two branches simultaneously, you would normally need to either clone the repo twice or stash and switch constantly.

Worktrees solve this. A worktree is an additional working directory linked to the same underlying git repository. You can check out a different branch in each worktree, and each has its own:

Working directory files
Index (staging area)
HEAD pointer

They share the .git object database, so history is shared but working state is fully isolated. No file conflicts, no accidental cross-branch contamination.

# Structure after adding two worktrees
/my-project/              ← main worktree (main branch)
/my-project-feat-auth/    ← linked worktree (feat/auth branch)
/my-project-feat-billing/ ← linked worktree (feat/billing branch)

Each directory is a fully functional repo checkout. You can run dev servers, tests, or Claude Code sessions in any of them independently.

Why Claude Code Uses Worktrees for Parallel Tasks

Claude Code subagents — separate Claude instances spawned to work on parallel tasks — need file isolation. If two subagents both modify /lib/utils.ts in the same directory, their changes will conflict and overwrite each other mid-task.

Worktrees solve this by giving each subagent its own complete copy of the working tree. Subagent A works in /project-feat-auth/, Subagent B works in /project-feat-billing/, and neither knows the other exists until you merge their branches.

This is the recommended pattern in the Anthropic Claude Code documentation for any parallel multi-agent workflow.

Setup: `git worktree add`

The basic command:

git worktree add <path> <branch>

Create a new branch and worktree in one step:

# From your main repo directory
git worktree add ../my-project-feat-auth -b feat/auth
git worktree add ../my-project-feat-billing -b feat/billing

This creates two new directories alongside your main repo, each checked out on a fresh branch.

Use an existing branch:

git worktree add ../my-project-hotfix hotfix/payment-crash

List active worktrees:

git worktree list

Output:

/Users/you/my-project               abc1234 [main]
/Users/you/my-project-feat-auth     def5678 [feat/auth]
/Users/you/my-project-feat-billing  ghi9012 [feat/billing]

Each worktree is a valid directory. You can cd into any of them and run any git command.

How to Spawn a Claude Code Subagent in an Isolated Worktree

The pattern is straightforward: create the worktree, then launch a Claude Code session in that directory.

Terminal-based parallel sessions (most common approach):

# Terminal 1: main work
cd /my-project
claude

# Terminal 2: auth feature
cd /my-project-feat-auth
claude "implement JWT token refresh logic in /lib/auth.ts"

# Terminal 3: billing feature
cd /my-project-feat-billing
claude "add Stripe webhook handler for subscription.updated events"

Each Claude instance operates in its own isolated worktree and cannot see or affect the files in the other directories.

Programmatic subagent spawning using the Agent SDK:

When orchestrating from a parent Claude session, you can spawn non-interactive subagents using the claude -p flag with a --cwd argument pointing to each worktree. The parent agent tracks completion signals (exit codes, output files) and merges results when both subagents finish.

The key invariant: each subagent gets a unique cwd pointing to its own worktree. Never point two concurrent agents at the same directory.

Use Cases

Running Two Features Simultaneously

The most common use case. You have two independent features that need to land in the same sprint. Instead of working on them sequentially, spawn parallel Claude instances in separate worktrees. A feature that might take 2 hours sequentially can be done in 1 hour in parallel.

Requirements for safe parallelism: the two features must touch different parts of the codebase. If both need to modify the same file, they will produce conflicting branches that require manual merge resolution.

Safe Experimentation

Worktrees are ideal for trying a risky approach without touching your working branch:

git worktree add ../my-project-experiment -b experiment/new-cache-layer
cd ../my-project-experiment
claude "rewrite the caching layer using Redis instead of in-memory store"

If the experiment works, merge the branch. If not, delete the worktree and branch cleanly.

Testing Without Touching Main

Run a full test suite or integration tests on a feature branch in a worktree while you continue developing on main in your primary directory. No stashing, no branch switching, no dev server restarts.

git worktree add ../my-project-test-run feat/new-api-layer
# In the test worktree terminal:
cd ../my-project-test-run && npm run test:e2e
# Your main worktree stays untouched and running

Hotfixes While Feature Work Is In Progress

# You're mid-feature on feat/auth in your main worktree
# An urgent hotfix arrives
git worktree add ../my-project-hotfix -b hotfix/login-crash main
cd ../my-project-hotfix
claude "fix the null pointer in /app/api/login/route.ts — users are getting 500s"
# Ship the hotfix, then return to feature work without touching your in-progress branch

No interrupted flow, no stashed changes.

Cleanup: `git worktree remove`

When you are done with a worktree — after merging the branch or discarding the experiment:

# Remove the worktree directory and deregister it
git worktree remove ../my-project-feat-auth

# Force remove if there are uncommitted changes you want to discard
git worktree remove --force ../my-project-feat-auth

Then delete the branch if you no longer need it:

git branch -d feat/auth

Worktrees that were removed without git worktree remove (e.g., the directory was deleted manually) leave stale entries. Clean them up:

git worktree prune

Performance Considerations

Disk space: Each worktree is a full working directory copy. For large Node.js projects, node_modules in each worktree multiplies disk usage. Symlink node_modules across worktrees or use a shared package manager cache to mitigate.

# After creating worktree, symlink node_modules instead of reinstalling
ln -s /my-project/node_modules /my-project-feat-auth/node_modules

This works if both worktrees are on the same branch baseline. If dependencies differ between branches, install separately.

Port conflicts: If you run dev servers in multiple worktrees, configure different ports per worktree using .env.local with PORT=3001, PORT=3002, etc.

Git operations: Operations like git fetch and git log work the same in any worktree — they all share the same .git repository. Commits in one worktree are immediately visible in others via git log.

IDE indexing: Some editors will re-index each worktree separately, which can be CPU-intensive on large projects. Open worktrees as separate workspace roots rather than nested folders.

FAQ

Q: Can I have the same branch checked out in two worktrees? No. Git prevents checking out the same branch in two worktrees simultaneously. Each worktree must be on a unique branch.

Q: Do CLAUDE.md files work in worktrees? Yes. Each worktree directory inherits CLAUDE.md files from its directory hierarchy, just like any normal Claude Code session. Your project-level CLAUDE.md is present in every worktree because it is part of the checked-out branch. For tips on writing a CLAUDE.md that works well across parallel sessions, see How to Write Effective CLAUDE.md Files.

Q: How many worktrees can I have at once? There is no hard limit, but each Claude Code session consumes API tokens and compute. Practically, 2–4 parallel subagents is the useful range before coordination overhead and API costs outweigh the parallelism benefit.

Q: Can worktrees be on separate machines or is this local-only? Worktrees are local only — they are additional directories on the same machine sharing the same .git repo. For multi-machine parallelism, you would need separate clones and a coordination mechanism.

Q: What happens to a worktree if the branch it's on gets force-pushed? The worktree working directory remains unchanged (it is not automatically updated), but git status will show it as diverged from the remote. Run git pull --rebase to realign.

Sources

→ Get Claude Code Power Prompts 300 — $29

Includes ready-to-run worktree setup scripts, parallel subagent orchestration templates, and 300 prompts covering multi-agent workflows from solo projects to team repos.