Claude Code Worktree — Git Isolation So Parallel Agents Don't Step On Each Other
As of 2026-10-20, Claude Code isolates parallel sessions with git worktrees: claude --worktree feature-auth creates a tree under .claude/worktrees/ on branch worktree-feature-auth; subagents can set isolation: worktree. Cleanup on exit follows what would be lost.
What a Worktree Is and Why It Matters
A git worktree is a separate working directory with its own files and branch, sharing the same repository history and remote as the main checkout. Claude Code runs each parallel session in its own worktree: claude --worktree feature-auth (or -w) creates .claude/worktrees/feature-auth/ at the repository root on branch worktree-feature-auth. Session A writes feature X and session B fixes bug Y without touching each other's files.
The EnterWorktree Tool & isolation Config
You can also ask Claude to work in a worktree during a session; it creates one with the EnterWorktree tool. Before entering a path outside the repository's .claude/worktrees/ directory, Claude Code asks for your approval; before v2.1.206, Claude could enter any existing worktree path without asking. A custom subagent can add isolation: worktree to its frontmatter so every dispatch gets a temporary worktree. Add .claude/worktrees/ to .gitignore, and use .worktreeinclude to carry .env and other ignored files into new worktrees.
Subagent worktrees and parallel agents
Subagents can run in their own worktrees: ask Claude to use worktrees for your agents, or add isolation: worktree to a custom subagent. Each subagent gets a temporary worktree that is removed automatically when it finishes without changes; one with changes stays on disk until the periodic sweep can remove it without losing work. Example: three agents rewrite auth, add unit tests and write migrations at once — file edits never collide, and you merge at the end. On exit, Claude checks for work: a clean unnamed session is removed automatically, one with changes prompts you to keep or remove, and -p runs are not cleaned up automatically.
Auto-Cleanup, Common Pitfalls, Team Conventions
When you exit an interactive worktree session, Claude checks for changed or untracked files and new commits: a clean unnamed session is removed automatically, a named session asks first, and one with changes asks whether to keep or remove it; -p runs are not cleaned up automatically. Common pitfalls: 1) branch name collisions across agents; 2) subagent worktrees with changes stay on disk until the periodic sweep; 3) forgetting to add .claude/worktrees/ to .gitignore. 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 a commit pointer; switching it means a checkout that overwrites files. A worktree is a separate working directory, so several branches can be checked out in different physical paths at once. That is the prerequisite for running agents in parallel.
Will subagent worktrees pollute the main repo?
No. Each subagent gets a temporary worktree; git tracks worktrees under .git/worktrees/<id>. A subagent worktree with no changes is removed automatically; one with changes stays until the sweep can remove it without losing work, so the main checkout stays clean.
Can I use worktrees with Claude Code from China?
Yes. Worktrees are local git and Claude Code client features; model inference goes through your configured QCode endpoint. Worktrees require a git repository; for other version control systems, configure WorktreeCreate and WorktreeRemove hooks to replace the git logic.
Run Parallel Claude Code Agents Through QCode
Model inference goes through QCode's API endpoint; worktrees run locally, so parallel sessions just use the commands above.
Start Your QCode Plan