Worktree Subagent Isolation Pattern
WorktreeIntermediate
Each Agent tool invocation gets its own temporary git worktree that auto-creates on start and auto-cleans when the subagent finishes without changes.
worktreesubagentisolationparallelgit
Pattern Code
# Worktree Subagent Isolation Pattern
## Basic Usage — isolation: "worktree"
```typescript
// In CLAUDE.md or custom subagent definition
// Each subagent gets its own git worktree automatically
// Parent agent launches isolated subagents
await Promise.all([
agent({
prompt: "Implement user authentication module",
isolation: "worktree", // <-- auto-creates .claude/worktrees/<random>
}),
agent({
prompt: "Implement payment processing module",
isolation: "worktree", // <-- separate worktree, no conflicts
}),
agent({
prompt: "Write integration tests for both modules",
isolation: "worktree",
}),
]);
```
## How It Works
```
Main worktree (your working directory)
├── .claude/worktrees/
│ ├── auth-abc123/ ← subagent 1's isolated copy
│ │ └── (full repo clone on separate branch)
│ ├── payment-def456/ ← subagent 2's isolated copy
│ │ └── (full repo clone on separate branch)
│ └── tests-ghi789/ ← subagent 3's isolated copy
│ └── (full repo clone on separate branch)
```
## Lifecycle
1. **Creation**: `git worktree add .claude/worktrees/<name> -b <branch>`
2. **Execution**: Subagent runs in isolated directory
3. **Completion**:
- If NO changes → worktree auto-removed (clean)
- If changes made → worktree + branch preserved
- Parent receives: { worktreePath, branch, hasChanges }
## Merge Strategy
```bash
# After subagents complete, merge results
git merge worktree/auth-abc123 --no-ff -m "feat: add auth module"
git merge worktree/payment-def456 --no-ff -m "feat: add payment module"
# Clean up merged worktrees
git worktree remove .claude/worktrees/auth-abc123
git worktree remove .claude/worktrees/payment-def456
```
## Benefits Over Manual Worktrees
- No setup scripts needed — just add `isolation: "worktree"`
- Auto-cleanup on no-change subagents (no stale worktrees)
- Branch naming handled automatically
- Works with existing git hooks and CI
- Compatible with Agent Teams for team-level isolation
Copy this pattern into your project configuration to implement.
Terminal Preview
Worktree Subagent Isolation Pattern
About Worktree Subagent Isolation Pattern
Claude Code patterns are proven architectural designs and workflow structures that help you tackle complex development scenarios. Worktree Subagent Isolation Pattern is a Worktree pattern at the Intermediate level that provides a tested, repeatable approach you can adapt to your projects for more efficient and consistent results.