Claude Code Worktree — Git Isolation So Parallel Agents Don't Step On Each Other
Every Claude Code session or subagent gets its own git worktree; file edits don't leak between them; cleanup is automatic when there's nothing to keep. This guide covers tools, config, parallel patterns, and gotchas.
What a Worktree Is and Why It Matters
A git worktree is an additional working directory attached to the same repo — its own working tree and branch, but sharing .git history and remote. Claude Code attaches each parallel session or subagent to its own worktree, so session A writing feature X and session B fixing bug Y never overwrite each other's files. Shared git metadata keeps commits, pushes, and log views consistent.
The EnterWorktree Tool & isolation Config
In a Claude Code session just say 'work in a worktree' and the model invokes EnterWorktree to create one. Or, in a custom subagent's frontmatter, set isolation: worktree so every dispatch of that subagent automatically gets an isolated worktree. Starting in v2.1.x background sessions also support worktree bg isolation, so long-running tasks no longer block your main dev branch.
/team-build Parallel Multi-Agent Mode
When /team-build dispatches multiple agents at once, each automatically receives worktree isolation and can operate on overlapping domains without conflict. Example: three agents simultaneously a) rewriting the auth module, b) adding unit tests, c) writing migration scripts — file edits never collide; you merge at the end. This is the core engineering value of worktrees for agent teams.
Auto-Cleanup, Common Pitfalls, Team Conventions
On exit, a worktree with no commits and no untracked files is removed automatically together with its temporary branch; if there are changes, the worktree path and branch are reported back. Common pitfalls: 1) branch name collisions across agents; 2) untracked files blocking cleanup; 3) integration with worktree-from-origin-main workflows requires fetching origin first. Teams should agree on a fixed branch prefix (e.g. wt/agent-<name>-<ts>) to avoid collisions.
FAQ
How is a worktree different from a regular git branch?
A branch is just a commit pointer — switching trees means a checkout that overwrites files. A worktree is an independent working directory: multiple branches can be checked out into different physical paths at once. This is the prerequisite for true parallel agent work.
Will subagent worktrees pollute the main repo?
No. Worktree paths live outside your main checkout, and git tracks them under .git/worktrees/<id>. Exit without commits and the entire worktree plus its temp branch is deleted automatically — main repo stays clean.
Can I use worktrees with Claude Code from China?
Yes. Worktrees are local git + Claude Code client features that run on your machine. Model inference goes through QCode's transparent gateway, giving you the same experience as overseas users.
Run Parallel Claude Code Agents Through QCode
QCode provides transparent access to all Claude models from inside China — worktree parallel workflows work with zero extra configuration.
Start Your QCode Plan