What you will be able to do
- Choose between subagents, agent view, agent teams, dynamic workflows and /batch for a large engineering change
- Explain what each git worktree keeps separate and what all worktrees share, and plan branches accordingly
- Decompose a fan-out so shared foundations land before agents branch, and files are partitioned by owner
- Pick the merge control that catches semantic conflicts between individually green agent branches
Key concept
One task, one worktree, one branch — Every parallel agent edits its own git checkout on its own branch, so file changes cannot collide while the agents run. Conflicts are left for integration time, which makes how you split the task and how you land the branches the real design work.
1.Choosing a fan-out shape
Parallel agent orchestration means splitting one large engineering change, such as a codebase-wide audit or a 500-file migration, across several Claude agents that run at the same time. Done well, the work finishes in a fraction of the time one session would take. Done badly, agents overwrite each other, each invent their own copy of the same shared code, and produce branches that pass on their own but break main when combined. The first design decision is who holds the plan. The general theory of lead and worker topologies is covered in multi-agent orchestration. Here the question is which Claude Code mechanism fits a given engineering job.
| Approach | Who coordinates | Use it when |
|---|---|---|
| Subagents | Claude delegates and collects results inside one conversation | A side task would flood the main conversation with search results, logs or file contents |
| Agent view (claude agents) | You: hand off background sessions and check back later | You have several independent tasks and want to step in only when one needs you |
| Agent teams | A lead with a shared task list and inter-agent messaging. Experimental and disabled by default | Workers must stay in sync, e.g. frontend, backend and tests each owned by a teammate |
| Dynamic workflows | A script holds the plan instead of Claude's turn-by-turn judgment | A job outgrows a handful of subagents: a codebase-wide audit or a 500-file migration |
| /batch | A skill that splits one large change into 5 to 30 worktree-isolated subagents | You want subagents plus worktrees packaged, not a new coordination style |
Cost and communication separate the two most common choices. A subagent returns a summary to its caller, so its token cost stays low. Each agent-team teammate is a separate Claude instance that messages its peers directly, so teams cost more and pay off only when workers need to discuss the work. Scale separates workflows from everything else. Subagents handle a few delegated tasks per turn, while a workflow runs dozens to hundreds of agents. Its intermediate results live in script variables, not in a context window, and an interrupted run can be resumed in the same session.
export const meta = {
name: 'audit-routes',
description: 'Audit every route handler for missing auth checks',
}
const found = await agent('List every .ts file under src/routes/.', {
schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})
const audits = await pipeline(found.files, file =>
agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)
return audits.filter(Boolean)In this script the decomposition is written down: one unit of work per file, under a label you can see in the progress view. That is why a workflow can be rerun, and why it is the natural fit when the split is mechanical. When the split needs judgment, for example deciding which module owns a cross-cutting change, a lead agent or a person should make it before any worker starts.
Checkpoint 1 of 8· Match them up
Match each Claude Code mechanism to the engineering job it fits best
Tap a term, then the definition that fits it.
Each mechanism is separated by who coordinates and by scale. Subagents return summaries inside one conversation. Agent view leaves coordination to you. Agent teams have a lead plus peer messaging. Workflows let a script hold the plan for dozens to hundreds of agents. /batch packages subagents and worktrees together.
“A script holds the plan instead of Claude’s turn-by-turn judgment: dynamic workflows.”Source: code.claude.com
2.What a worktree isolates and what it shares
A git worktree gives each agent a separate checkout: its own directory of files, its own staging state and its own HEAD, on its own branch. Every worktree writes into the same repository store. Commits and branches made in one are visible from all the others straight away. Separate files avoid collisions, and the shared store means nothing has to be pushed or copied between agents.
The shared store comes with one restriction that shapes branch planning. A branch that is checked out in one worktree stays bound to that worktree, so another agent that wants to build on it creates a new branch from it instead of checking it out. Claude Code follows this rule. When a session in a worktree spawns a copy whose task builds on its work, the copy is told to base a new branch on the original's branch. The working rule for a fleet is one task per agent, one branch per task, and one worktree per branch. HEAD is also per worktree: inside a worktree, a reference to HEAD resolves to that worktree's HEAD, not the main checkout's.
There are three ways into a worktree. An interactive session starts in one with claude --worktree feature-auth. A background session needs claude --bg --worktree, because Claude Code refuses a background session's edits in your main checkout. A custom subagent gets a fresh worktree each time it runs when its definition declares isolation: worktree.
---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---
Apply the requested refactor across every affected file, then run the tests
and report the results.Claude Code enforces this isolation itself instead of trusting the agent to stay inside its worktree. It blocks Edit and Write calls that target the main checkout, and Bash commands whose working directory resolves there. It also blocks commands that redirect git into the main checkout through git -C, --git-dir, GIT_DIR or GIT_WORK_TREE. When it cannot tell from the command text where git will run, it refuses the command and tells Claude how to rewrite it, and that check cannot be turned off. One thing does cross worktree boundaries: answering “Yes, and don’t ask again” in one worktree saves the rule to the main checkout's .claude/settings.local.json, and the rule then applies in every worktree of the repository.
Checkpoint 2 of 8· Check yourself
In a fleet migration, agent B's task builds on work that agent A has committed to feat/a. That branch is still checked out in agent A's worktree. What should agent B do in its own worktree?
A branch that is checked out in one worktree stays bound to it, so another agent can't check it out. Agent B starts a new branch from feat/a. No push is needed because the store is shared, and Claude Code blocks git redirects like git -C that point outside the agent's own worktree.
“base its new branch on yours, since your branch stays checked out in your worktree”Source: code.claude.com
Checkpoint 3 of 8· Exam question
Fennel Games runs the build pipeline for its live-service multiplayer title, and a team there runs eight coding agents, each in its own git worktree of one repository. An engineer is planning how to assign branches to the agents and ran a short trial first. Disk usage after creating all eight worktrees grew by little more than the size of the checked-out files, even though the repository history is several gigabytes. A commit made by the agent in worktree 3 on a new branch showed up in the branch list of worktree 5 straight away, with no push. Files staged in worktree 3 did not appear in worktree 5's status. Asking worktree 6 to check out the same branch was refused, although the two agents edit different files. Which statement about this setup is accurate?
Correct answer: C — Each worktree has its own working directory and index and shares one object database, and a given branch can be checked out in only one worktree at a time.
- A. Incorrect: linked worktrees share the repository's object database rather than carrying their own, and git refuses to check out a branch that another worktree already has, whichever files each agent edits.
- B. Incorrect: the index is per worktree, not shared. Each agent stages in its own index, so there is no need to keep staged paths disjoint. The one-worktree-per-branch rule is real but does not rescue the claim.
- C. Correct: a separate working directory and index per worktree isolate each agent's files, the shared object database keeps the copies cheap, and git allows a branch in only one worktree, so each agent needs its own branch.
- D. Incorrect: branches and other refs live in the shared repository, not per worktree. A branch created or committed to in one worktree is immediately visible from the others, with no push needed.
3.Decomposing work so agents don't redefine shared code
Worktrees stop agents from colliding in their files, but they do nothing to stop collisions in the design. Picture six agents each adding an endpoint, and each needing a new shared ApiError type. Each agent is isolated, so none of them can see the type another agent is still writing. Each writes its own version into the same types file, and the merge produces six definitions with different shapes.
The tempting fixes don't work. Telling each agent to search for an existing ApiError before writing finds nothing, because the type doesn't exist in any agent's checkout yet. Having each agent define the type in its own folder and unifying the versions after merge only moves the conflict later, after six callers already depend on six shapes. Merging with a strategy that keeps one side's text drops the other variants without reconciling them. What works is landing the shared foundation first, as its own small change to main. Then branch every agent from that commit and tell each one to import the type, not redefine it.
Where agents branch from depends on worktree.baseRef, so check it before relying on that order. The default, "fresh", branches from the repository's default branch on the remote. That means the shared commit has to be pushed to the remote's main before fan-out, or fresh worktrees won't contain it. If the foundation exists only as local commits, "head" branches from your current local HEAD, unpushed commits included.
{
"worktree": {
"baseRef": "head"
}
}With the shared code in place, partition the remaining work by file ownership, and make claiming a task an atomic step. Agent teams make partitioning mandatory, because teammates share one checkout rather than getting a worktree each. A team's shared task list lets a teammate self-claim the next unassigned, unblocked task. Anthropic's 16-agent C compiler experiment used a simpler claim: an agent locked a task by committing a file such as current_tasks/parse_if_statement.txt. If two agents claimed the same task, git's synchronization forced the second one to pick another.
Checkpoint 4 of 8· Check yourself
You commit a shared ApiError type to your local main but don't push it. Then you fan out six worktree-isolated subagents without changing any worktree settings. Every agent reports that ApiError doesn't exist. What explains this, and what fixes it?
With the default "fresh", a worktree starts from the remote's default branch, so a commit that exists only locally is missing. You can push the foundation commit before fan-out, or use "head" so new worktrees carry your unpushed commits.
“"fresh" (default): branch from the repository’s default branch on the remote, usually main, so the worktree starts from a clean tree matching the remote.”Source: code.claude.com
Checkpoint 5 of 8· Check yourself
An agent team with three teammates will add features that could touch some of the same source files. How should the lead set up the work so that teammates don't overwrite each other?
Teammates are not isolated in worktrees, so nothing keeps their file edits apart. The split itself has to give each teammate a separate set of files.
“Agent teams don’t isolate teammates in worktrees, so partition the work so each teammate owns a different set of files.”Source: code.claude.com
Checkpoint 6 of 8· Exam question
Heron Insurance is adding claims-portal endpoints to its production policy-administration service, and a lead engineer fans out six agents, each assigned one endpoint. Every endpoint must return failures through a new shared ApiError type. Each agent works in its own git branch and checkout, and none can see the others' work until its branch is merged. In an earlier trial run, every agent added its own variant of the type to the same types file. Merging the branches produced conflicting definitions that disagreed on shape, such as error code fields and detail payloads. The endpoint handlers on each branch were written against that branch's own variant. Heron wants all six endpoints merged this week with no reworked handlers. What is the most effective strategy?
Correct answer: D — Commit the ApiError type to main in its own small change, then create the six agent branches from that commit and tell the agents to import it, not redefine it.
- A. Incorrect: the six agents run in parallel on separate branches, and each sees only its own checkout. An instruction to search for an existing ApiError finds nothing, so every agent still writes its own version.
- B. Incorrect:
-X theirskeeps the incoming side of each conflicting hunk, so earlier agents' definitions are dropped. Their endpoints were written against a shape that no longer exists, so the type checker reports rework across several branches while the shape disagreement stays unresolved. - C. Incorrect: separate files give six different ApiError shapes, and the endpoints are built on them before anyone reconciles them. The consolidation step repeats the same shape disagreement later, after more code depends on each variant.
- D. Correct: a type every endpoint needs is a sequencing dependency, not parallel work. Landing it first and branching from that commit gives all six agents one definition to import, so their branches no longer overlap in the types file.
4.Merging many agent branches without breaking main
Every agent branch is tested against a snapshot: whatever main looked like when its worktree was created. Eight branches can each pass CI against that snapshot and still break main when combined. Suppose one branch renames a helper and another adds a new call to the old name. Git merges both cleanly, because no lines overlap, and the build fails. This is a semantic conflict. Text-level merge tools can't detect it, and per-branch CI never runs the combination.
The control that catches it is landing branches one at a time, each tested against the current main. A merge queue does this mechanically. It rebases each pull request onto the latest main, re-runs CI on that combined result, and lands the change only if CI passes. The next PR in the queue then rebases onto a main that already includes it. The alternatives miss the failure. Running the full suite locally, or running the suites for areas other agents own, still tests against the stale snapshot. A human reading diffs for interactions has to predict the combined behaviour instead of running it, and that gets harder with every extra branch.
The C compiler harness built the same discipline into each agent's loop. After finishing a task, the agent pulled the latest upstream, merged the other agents' changes, and only then pushed. Merge conflicts were frequent, and the agents resolved them. Landing is often deliberately left out of the agent's role. A session dispatched from agent view commits and pushes its branch and opens a draft pull request when the task calls for it. It never pushes to main, force-pushes, or merges. That leaves the merge gate to you. Gating merges on CI is covered in verification and AI code review operations.
Checkpoint 7 of 8· Check yourself
Eight agent branches each passed CI in their own worktrees. After all eight were merged, main fails to build. One branch renamed a helper, and another added a call to the old name. Git reported no conflicts. Which control would have stopped this before it reached main?
This is a semantic conflict. Each branch was tested only against the snapshot of main it started from, so the combined code was never tested. Rebasing each change onto the current main and re-running CI before it lands tests that combination. More tests on each branch, or other agents' suites run in a stale worktree, still miss the combined result. A reviewer would have to predict how eight branches interact instead of running them together.
“Claude works on the task, then pulls from upstream, merges changes from other agents, pushes its changes, and removes the lock.”Source: www.anthropic.com
Checkpoint 8 of 8· Exam question
Willow Energy runs a grid-balancing platform in a single monorepo, and it has assigned eight coding agents to separate feature branches in parallel, each working on a different service area. Every branch passes the complete CI suite when run on its own, and every agent already runs that suite before opening its PR. Engineers merge the approved PRs into main one after another as they arrive. Three times this week the main build has gone red after a merge, each time because two changes that were individually correct conflicted in behavior, such as one branch renaming a shared field while another began relying on the old name. Reviewers approve diffs one at a time and cannot see what the other open branches will look like once merged. What control most directly prevents this?
Correct answer: C — Merge through a queue that rebases each PR onto the current main and re-runs CI on that combined result before landing it.
- A. Incorrect: each branch already passes the full suite in isolation; the failure only exists in the combination, which local runs cannot see.
- B. Incorrect: a reviewer cannot reliably predict interactions across eight in-flight branches, and this makes human review the bottleneck without a deterministic check.
- C. Correct: testing the post-merge combination before landing is an enforced gate, and it catches interaction failures that per-branch CI cannot.
- D. Incorrect: an agent cannot test against other agents' unmerged edits, so running other suites on its own branch still tests the same isolated code.
Sources
(6)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/agentsOfficial docs
“/batch is a skill that has Claude split one large change into 5 to 30 worktree-isolated subagents.”
↩︎ Choosing a fan-out shape“Agent teams don’t isolate teammates in worktrees, so partition the work so each teammate owns a different set of files.”
↩︎ Decomposing work so agents don't redefine shared code“Worktrees give each session a separate git checkout, so parallel sessions each edit their own copy of the files.”
↩︎ Key concept“Agent teams don’t isolate teammates in worktrees, so partition the work so each teammate owns a different set of files.”
↩︎ Exam trap 2“A script holds the plan instead of Claude’s turn-by-turn judgment: dynamic workflows.”
↩︎ Checkpoint - 2.https://code.claude.com/docs/en/workflowsOfficial docs
“Dozens to hundreds of agents per run”
↩︎ Choosing a fan-out shape - 3.https://code.claude.com/docs/en/agent-teamsOfficial docs
“Higher: each teammate is a separate Claude instance”
↩︎ Choosing a fan-out shape - 4.https://code.claude.com/docs/en/worktreesOfficial docs
“git commands in a worktree write to the main repository’s shared .git directory”
↩︎ What a worktree isolates and what it shares“Inside a worktree, "head" resolves to that worktree’s HEAD, not the main checkout’s.”
↩︎ What a worktree isolates and what it shares“Claude Code refuses a background session’s edits in your main checkout until the session calls EnterWorktree, which it doesn’t have.”
↩︎ What a worktree isolates and what it shares“Claude Code blocks a Bash or Monitor command that redirects git into the main checkout.”
↩︎ What a worktree isolates and what it shares“branch from your current local HEAD, so the worktree carries your unpushed commits and feature-branch state.”
↩︎ Decomposing work so agents don't redefine shared code“git commands in a worktree write to the main repository’s shared .git directory”
↩︎ Exam trap 1“branch from the repository’s default branch on the remote, usually main, so the worktree starts from a clean tree matching the remote.”
↩︎ Exam trap 3“"fresh" (default): branch from the repository’s default branch on the remote, usually main, so the worktree starts from a clean tree matching the remote.”
↩︎ Checkpoint - 5.https://code.claude.com/docs/en/agent-viewOfficial docs
“base its new branch on yours, since your branch stays checked out in your worktree”
↩︎ What a worktree isolates and what it shares“Never: pushing to main or master, force-pushing, and merging.”
↩︎ Merging many agent branches without breaking main - 6.https://www.anthropic.com/engineering/building-c-compilerSecondary source
“If two agents try to claim the same task, git's synchronization forces the second agent to pick a different one.”
↩︎ Decomposing work so agents don't redefine shared code“Claude works on the task, then pulls from upstream, merges changes from other agents, pushes its changes, and removes the lock.”
↩︎ Merging many agent branches without breaking main“Merge conflicts are frequent, but Claude is smart enough to figure that out.”
↩︎ Merging many agent branches without breaking main