Worktrees: Parallel Claude Code Sessions Without Collisions
Git worktrees let you check out multiple branches simultaneously in separate directories—each with its own working tree, staging area, and HEAD. Claude Code becomes exponentially more useful when you can run one agent on a feature branch and another on main without waiting for the first to finish.
This guide explains the worktree lifecycle, how Claude Code's --worktree flag wires isolation, the .worktreeinclude directive for sparse checkouts, and the real failure mode: branch divergence. We'll trace a scenario where two agents safely refactor different parts of a monorepo in parallel, merge, and catch the one conflict that matters.
What Are Worktrees and Why They Matter
In a normal Git repo, you have one working tree tied to HEAD. Checking out a different branch moves your files on disk, which blocks parallel work. Worktrees solve this: each worktree is a separate directory with its own branch, staging area, and index, but they all share the same .git/objects database.
For Claude Code, this is essential. Without worktrees, an agent on feature-A must finish, commit, and push before you can work on bugfix-B on main. With worktrees, both run simultaneously: claude agent --worktree feature-A and claude agent --worktree bugfix-B in separate terminal sessions. Each agent sees its own file state and never interferes with the other.
Quick reference
- Worktrees share
.git/objectsand.git/refs/remotes; separate working trees. - Each worktree has its own
.git/index(staging area). - Creating a worktree checks out a branch in a new directory.
- Deleting a worktree removes the directory but leaves the branch.
- No locking: two agents on the same branch will conflict; always use separate branches.
Remember this
Worktrees enable parallel branch work. One repo, multiple worktrees, zero interference between branches.
Creating Isolated Git Worktrees
A worktree is a directory. You create it with git worktree add, which checks out a branch into a new path. To resume, you enter that directory; to clean up, you remove it. The --detach flag creates a headless worktree for temporary work; without it, you must specify a branch (new or existing).
Best practice: name worktrees after their branches. If you're creating a worktree for feature-X, use ../worktrees/feature-X or ../feature-X-work. This makes cleanup predictable: when the branch is merged and deleted, delete the worktree directory.
Quick reference
- Create:
git worktree add ../feature-X feature-X(ormain,develop). - List:
git worktree listshows all active worktrees. - Move into the worktree directory; files are independent.
- Commit, push, and merge normally from the worktree.
- Clean up:
rm -rf ../feature-X && git worktree pruneafter branch deletion.
Remember this
Create worktrees with git worktree add. Each worktree is a directory with its own branch. Cleanup after merge.
Using the --worktree Flag
Claude Code's --worktree flag tells the SDK which worktree directory to bind to. Without it, Claude defaults to the current .git (the main working tree). With it, Claude scopes all file operations to that worktree and respects its separate staging area.
When you run claude agent --worktree ../worktrees/feature-A, Claude:
1. Validates that the path is a valid worktree (has .git file pointing to main repo).
2. Sets the working directory to that worktree.
3. All file reads, writes, and Git operations happen in that context.
4. Commit and push respect that worktree's branch.
Quick reference
- Syntax:
claude agent --worktree <path> - Path can be absolute or relative.
- Claude validates it's a worktree before starting.
- All git operations use that worktree's context.
- File paths in the agent are relative to the worktree root.
Remember this
Always use --worktree when running multiple agents in parallel. Each agent gets its own branch context.
Preventing Merge Conflicts with Isolation
Isolation doesn't eliminate conflicts—it makes them explicit and manageable. When agent-A and agent-B both modify the same file, Git will detect the conflict at merge time, not during execution.
The key: design worktrees by responsibility. If feature-A owns utils.ts and bugfix-B owns auth.ts, they never conflict. If both touch package.json, Git will halt the merge and ask you to resolve.
Claude Code can help here. After a merge conflict, you can run claude agent --worktree . --input "resolve merge conflicts" on the merge commit, and Claude will read the conflict markers and suggest a resolution. This is faster than manual resolution and scales to large teams.
Quick reference
- Isolation prevents concurrent modification of the same file.
- Conflicts are caught at merge, not during work.
- Always communicate ownership: who owns which files?
- For shared files (package.json, .env), synchronize before merge.
- Use Claude to resolve conflicts: commit conflict markers, ask Claude to fix.
Remember this
Parallel isolation makes conflicts explicit. Design worktrees by file ownership. Use Claude to resolve conflicts post-merge.
Subagent Isolation in Worktrees
A subagent is a child Claude Code session spawned by a parent agent. Subagents inherit the parent's working tree context—they see the same files, staging area, and branch. For true parallelism, parent and subagents need separate worktrees.
Example: A parent agent orchestrates a codebase audit. It spawns two subagents: one for tests, one for linting. Each subagent could work on the same branch (sharing state) or different branches (isolated). Isolated subagents are safer for large changes; shared is faster for reads.
Quick reference
- Subagents inherit parent's --worktree flag.
- To isolate: parent creates worktrees, passes --worktree to each subagent spawn.
- Shared worktree: subagent sees uncommitted changes from parent.
- Separate worktree: subagent sees clean branch state, merges back to parent's branch.
- Always synchronize after subagent: git pull to get subagent's commits.
Remember this
Subagents in separate worktrees are isolated. Parent orchestrates and merges subagent work.
`.worktreeinclude` for Selective Checkout
In a monorepo, you might have 10 packages but only care about 2. Sparse checkouts let you download only the files you need, reducing I/O and context. The .worktreeinclude file (similar to .gitignore) tells Git which paths to include in the working tree.
When Claude Code loads a worktree with sparse checkout, it only sees the included files. This speeds up agent startup, reduces indexing time, and avoids irrelevant file noise. Subagents inherit the sparse checkout rules, so they see the same view.
Quick reference
- Create
.worktreeincludewith patterns (one per line). - Patterns are relative to repo root:
packages/ui/,src/,.github/. - Git sparse-checkout enabled during worktree creation.
- Subagents see the filtered file tree.
- Disable sparse checkout:
git sparse-checkout disable.
Remember this
Sparse checkout speeds worktree load and reduces noise. Define .worktreeinclude in repo root; enable with --sparse flag.
Real Scenario: Refactor and Bug Fix in Parallel
You have a Next.js app. Main branch is stable. A feature branch (feature-refactor) needs a large utils refactoring. A bugfix branch (bugfix-security) has a critical auth fix. You want both merged today.
Without worktrees: refactor agent starts, modifies 15 files, commits, pushes. Then bugfix agent starts, has to wait. Total time: ~1 hour.
With worktrees: both agents start simultaneously. Refactor agent gets feature-refactor worktree, bugfix agent gets bugfix-security worktree. They run in parallel. Refactor takes 35 min, bugfix takes 20 min. Both finish in 35 min. You merge feature-refactor to main, then bugfix-security to main. One conflict in package.json (both bumped version). Claude resolves it. Merged and deployed in 40 min total.
Quick reference
- Create worktrees:
git worktree add ../refactor feature-refactorand../bugfix bugfix-security. - Run agents:
claude agent --worktree ../refactor --input "refactor utils.ts and helpers.ts". - Second terminal:
claude agent --worktree ../bugfix --input "fix authentication bypass"(simultaneous). - Monitor: both agents run in parallel, independent file states.
- Merge: after both agents commit/push, merge to main. Resolve conflicts if any.
Remember this
Worktrees enable parallel work. Two agents on different branches run simultaneously, merging when done.
Key takeaway
Worktrees are the foundation for large-team Claude Code workflows. Always use separate worktrees for parallel agents. After work completes, merge back to main and clean up the worktree directory. For complex orchestration, read the dynamic workflows guide on fan-out patterns and state management. For monorepo-scale configurations, see monorepo setup.
Polo Khan
Lead Author & Systems ArchitectSoftware engineer and distributed systems architect specializing in backend scalability, cloud-native infrastructure, databases, and AI engineering workflows. Author and maintainer of Core Concept Learning.
Related Articles
Explore this topic