No More Git Conflicts: Worktree Isolation for Parallel Claude Code Agents

Set isolation: 'worktree' on any agent() call in a Claude Code Workflow script and each subagent gets its own isolated git checkout — 50 parallel file-writing agents, zero branch conflicts.

When you fan out agents in a Claude Code Workflow and each one touches the filesystem, they race. Agent A edits src/auth.ts, agent B also edits src/auth.ts, and whichever writes last wins — silently clobbering the other's work. The fix is one line.

The pattern

// In a Claude Code Workflow script
const results = await parallel(files.map(file => () =>
  agent(
    `Review ${file} for security issues and apply fixes`,
    {
      label: `fix:${file}`,
      isolation: 'worktree',   // each agent gets a fresh git checkout
    }
  )
))

Each isolation: 'worktree' agent gets:

• A fresh git worktree add checkout of the current branch
• A clean working directory that tracks changes relative to HEAD
• Auto-cleanup: if the agent made no changes, the worktree is deleted automatically; if it made changes, the path and branch are returned so you can review and merge

Collecting results

const results = await parallel(files.map(file => () =>
  agent(`Fix security issues in ${file}`, { label: `fix:${file}`, isolation: 'worktree' })
))

// null = no changes (worktree auto-cleaned); non-null = branch with changes
const changed = results.filter(Boolean)
console.log(`${changed.length}/${files.length} files had fixable issues`)

// Review and merge each changed branch:
// git merge <branch-name> for each entry in changed

When to use it

Use worktree isolation when:

• Multiple agents write to overlapping file paths (refactors, linting sweeps, security audits, code generation)
• You're running more than ~5 parallel agents on a shared codebase
• You want a review or merge step before changes land on main

Skip it for:

• Read-only agents (analysis, search, summarization) — worktree setup adds ~200–500ms and disk per checkout

This is the pattern that let Alberta's cybersecurity team run 50 parallel audit agents across 466 million lines of code — each agent scanned its own isolated slice, zero conflicts.

Sources: Workflow docs — Claude Code · Alberta Government + Claude Code case study — Anthropic