Subagent Worktree Isolation
Setting isolation: worktree in AGENT.md gives each subagent spawn its own git branch and working directory. This is what enables parallel subagents to edit the same codebase without conflicts, and what makes /batch work at 30 agents simultaneously.
Quick Reference
- →isolation: worktree in AGENT.md frontmatter creates a separate worktree per agent spawn
- →Each spawn gets its own branch: claude/agent-{id}
- →Agents work in parallel without file conflicts — each in its own isolated directory
- →Auto-cleanup: no commits = worktree removed; commits = branch kept with path returned
- →Shared across all isolated agents: git history, CLAUDE.md, settings.json
- →Team Lead pattern: spawn N isolated subagents, collect branch names, merge sequentially
- →Shipped stable in v2.1.49 (February 19, 2026)
- →Known issue (March 2026): isolation can silently fail — verify the worktree was created
What isolation: worktree Does
Every time an agent with isolation: worktree is invoked, Claude Code creates a brand-new git worktree for that specific spawn. Two invocations of the same agent create two separate worktrees on two separate branches. They can work on the same files without conflict because they are in different directories.
Without isolation, all subagent spawns work in the parent session's directory. If two subagents both edit src/auth.ts, the second write overwrites the first. With isolation: worktree, each agent has its own directory — both can edit src/auth.ts, and both versions are preserved on separate branches.