Worktree Isolation in Claude Code: Parallel Work Without Conflicts

Git worktrees let you check out multiple branches of the same repository in separate directories simultaneously — and Claude Code's --isolation worktree flag automates this for agentic tasks. Instead of stashing your work or switching branches, each Claude agent gets its own isolated copy to work in, then you review the diff and merge. This guide covers manual worktree patterns and the automated isolation built into Claude Code.

Why Worktrees Matter for AI-Assisted Development

Without worktrees, running Claude on a long refactor means your working branch is dirty while Claude works. You can't switch to a bug fix without either waiting or stashing. With worktrees:

repo/
├── main/           (your current working branch)
├── feature-auth/   (Claude working on auth refactor)
└── hotfix-404/     (you fixing a production bug)

Three branches, three directories, all simultaneously. No switching, no stashing, no conflicts.

Manual Worktree Pattern

# Create a new worktree for a feature branch
git worktree add ../my-repo-feature-auth feature/auth-refactor

# Claude works in the isolated directory
cd ../my-repo-feature-auth
claude "Refactor the entire auth module to use JWT tokens.
Use the patterns in src/auth/current-implementation.ts as reference.
Run bun run typecheck after each file change."

# Review the diff from your main directory
cd ../my-repo
git diff HEAD..feature/auth-refactor

# Merge if satisfied
git merge feature/auth-refactor

# Clean up
git worktree remove ../my-repo-feature-auth

Claude Code's Built-In Worktree Isolation

The Agent tool supports isolation: "worktree" which automates this pattern:

# When spawning a sub-agent with worktree isolation
Agent({
    "description": "Auth refactor",
    "prompt": "Refactor the auth module to use JWT tokens.",
    "isolation": "worktree"
})

What happens automatically:

1. Claude creates a new git branch: claude/[task-slug]-[timestamp]
2. Creates a worktree for that branch
3. Agent runs all changes in the isolated worktree
4. If the agent makes no changes, the worktree is cleaned up
5. If changes are made, the branch and worktree path are returned for review

Parallel Feature Development

Run multiple Claude agents on independent features simultaneously:

# Terminal 1: Backend API
git worktree add ../repo-api-work feature/user-api
cd ../repo-api-work
claude --print "Implement the user CRUD API endpoints following CLAUDE.md conventions"

# Terminal 2: Frontend components (simultaneously)
git worktree add ../repo-ui-work feature/user-ui
cd ../repo-ui-work
claude --print "Implement the user management React components"

# Terminal 3: Tests (simultaneously)
git worktree add ../repo-tests-work feature/user-tests
cd ../repo-tests-work
claude --print "Write integration tests for the user management feature"

All three run at the same time. When done, review each diff and merge in order.

Risky Refactor Pattern

When attempting a large refactor you're not sure will work out:

# Create isolation branch before attempting
git worktree add ../repo-experiment experiment/large-refactor

cd ../repo-experiment
claude "Refactor all database calls to use the new Repository pattern.
Files to change: all files in src/db/ and any file that imports from src/db/.
If any typecheck fails, stop and report the error rather than continuing."

# Evaluate the result
cd ../repo-experiment
git diff HEAD  # See what changed
bun run typecheck  # Verify it works
bun run test  # Run tests

# If it looks good, bring it to main
cd ../repo-main
git merge experiment/large-refactor

# If it doesn't work, discard cleanly
git worktree remove ../repo-experiment
git branch -D experiment/large-refactor

No mess on your main working branch.

Worktree with CLAUDE.md Inheritance

Worktrees inherit CLAUDE.md from the root repository since they share the same git history. You don't need to copy or symlink CLAUDE.md — it's automatically present in every worktree.

# Main repo has CLAUDE.md at root
ls my-repo/CLAUDE.md  # exists

# Worktree automatically has it
ls my-repo-worktree/CLAUDE.md  # same file, same content

This means all your project conventions apply consistently whether you're working in the main checkout or a worktree.

Common Patterns

Pattern: Safe dependency upgrade

git worktree add ../repo-deps-upgrade test/dependency-upgrade
cd ../repo-deps-upgrade

claude "Upgrade all dependencies to their latest versions.
Run bun update.
Then run bun run typecheck and bun run test.
Report any breaking changes and either fix them or document what would need to change."

Pattern: A/B implementation comparison

# Implementation A
git worktree add ../repo-impl-a experiment/approach-a feature/new-search
cd ../repo-impl-a
claude "Implement search using Elasticsearch approach"

# Implementation B (simultaneously)
git worktree add ../repo-impl-b experiment/approach-b feature/new-search
cd ../repo-impl-b
claude "Implement search using PostgreSQL full-text search approach"

# Compare both
git diff experiment/approach-a..experiment/approach-b

Pattern: Hotfix while feature work is in progress

# Claude is working on a big feature in worktree
# Production bug comes in — handle it without disturbing feature work
git worktree add ../repo-hotfix hotfix/critical-bug main

cd ../repo-hotfix
claude "Fix the null pointer error in UserService.findById.
The error is in src/services/user.service.ts line 84.
Run the unit tests after fixing."

# Deploy hotfix
cd ../repo-hotfix
git push origin hotfix/critical-bug
gh pr create --base main --title "hotfix: null pointer in UserService"

Cleaning Up Worktrees

# List all worktrees
git worktree list

# Remove a specific worktree
git worktree remove ../repo-feature-auth

# Remove worktree and its branch
git worktree remove ../repo-feature-auth
git branch -D feature/auth-refactor

# Prune stale worktree references
git worktree prune

Frequently Asked Questions

Do worktrees use double the disk space? No — worktrees share the .git directory and object storage. The overhead is only the working tree files (source code), not the git history. For a 100MB repository, a worktree adds roughly 100MB of working files.

Can I run npm install or bun install in a worktree? Yes, but you need to run it separately in each worktree since node_modules isn't shared. This adds disk usage but ensures dependency isolation between branches.

What's the difference between a worktree and a fresh clone? Worktrees share the same .git directory — they see the same branches, remotes, and history. Clones are fully independent. Worktrees are faster to create, use less disk, and stay in sync automatically.

Can two worktrees be on the same branch? No — git prevents two worktrees from checking out the same branch simultaneously. This is a feature: it prevents you from accidentally having two different states of the same branch.

Does Claude Code's --isolation worktree push the branch automatically? No — it creates a local worktree and branch. You review the changes and push/merge manually. This is intentional: you stay in control of what enters your main branch.

Related Guides

• Background Tasks in Claude Code: The Complete Playbook — Parallel agent execution
• Git Workflows in Claude Code: Branching, PRs, and Commits — Git integration
• Claude Code Complete Guide — Full Claude Code reference

Go Deeper

Power Prompts 300 — $29 — Worktree workflow prompts including parallel feature development coordination, risky refactor patterns with validation gates, and the A/B implementation comparison template.

→ Get Power Prompts 300 — $29

30-day money-back guarantee. Instant download.