One Option Stops Parallel Claude Agents From Stepping on Each Other: isolation: worktree

Add isolation: "worktree" to any Claude Code agent call — it gets its own git branch and file system, so parallel agents never touch each other's uncommitted files.

When two Claude Code sessions run against the same repo simultaneously, they share files on disk. One session's in-progress edit is visible (and dangerous) to the other. With isolation: "worktree", each agent gets a fresh git worktree: its own directory, its own branch, no interference.

Add it to any agent definition

In your agent's frontmatter:

---
model: claude-opus-5
isolation: worktree
---

Or in the Agent SDK:

Agent({
    description: "Fix the auth bug",
    isolation: "worktree"
})

How cleanup works

Worktrees auto-remove if the agent makes no changes. If changes were made, the worktree path and branch are returned — review and merge at your own pace. Run git worktree prune weekly to catch stale worktrees from abandoned sessions; a cron or a pre-push hook works well for this.

When to use it

• Any fan-out workflow spawning multiple code-writing agents (migrations, multi-file fixes, parallel feature branches)
• Automated PR pipelines where agents work on separate files concurrently
• CI agents that need an isolated environment without a full Docker container

The /batch command in Claude Code uses isolation: worktree automatically for each spawned agent. The desktop app makes it the default per tab — you get this behavior interactively without any configuration.

Sources: Claude Code Power User Tips — support.claude.com · Git Worktrees in Claude Code — Claude Directory · Parallel Agents Without Context Switching — Developers Digest