Isolation & Worktrees

The failure mode is almost always the same shape. An engineer reads that running several coding agents at once is the new way to work, opens four terminals against one checkout, and points a different task at each. By lunch, two agents have written to the same config file forty minutes apart, one session has silently rebased itself onto the other’s half-finished edit, and a third aborted mid-tool-call when its working directory changed under it. The afternoon goes to archaeology: which agent wrote this line, was it meant to survive, and why does the test suite fail in a way none of the four sessions individually produced. Four agents running in parallel netted out to something less than two developers’ worth of usable work, and most of the loss was not in the agents — it was in the shared filesystem underneath them.

The fix that has become standard practice is not a coordination protocol or a smarter scheduler. It is a decade-old git feature almost nobody used for this purpose until agents made the collision problem acute: give every concurrent session its own working directory. This chapter is about that mechanism — what it actually solves, what it does not, and the shape of the workflow that makes running several agents on one repository tractable rather than merely survivable.

What a worktree actually buys you

A git worktree is a separate working directory with its own files and branch, sharing the same repository history and objects as the main checkout. This Library’s Volume IV introduced the mechanism already, in the chapter on sandboxing and blast radius, and was explicit that a worktree is not a security boundary — it isolates one session’s file edits from another’s, and nothing else. A session with full shell access inside a worktree can still reach anything outside it that the operating system permits; the isolation is real but narrow, aimed at exactly one failure mode: two writers touching the same file in real time. That framing still holds here. What changes in a multi-agent setting is that the narrow thing worktrees solve is precisely the thing that breaks first when the number of concurrent agents on one codebase goes from one to several.

The mechanism is deliberately unglamorous. Each worktree gets its own directory, its own branch, and its own staging area, but all of them point at the same object database and share the same commit history and remote. Claude Code documents this directly: running each session in its own worktree means edits in one session never touch files in another, and both the CLI’s `--worktree` flag and the desktop app now create one automatically per session for exactly this reason. That last property — shared history, divergent working directories — is what makes the whole approach tractable rather than merely safe. Four agents in four completely separate clones would never collide either, but merging their work back together would mean reconciling four unrelated histories by hand. Four agents in four worktrees of the same repository are, from git’s point of view, four branches waiting to be diffed and merged in the ordinary way.

Review the diffs, merge the winner

Isolation is the precondition, not the workflow. The actual practice that has emerged around parallel agents looks less like an assembly line and more like a bake-off: each agent works alone in its own worktree and branch, produces a complete diff, and a human — or, increasingly, an automated judge — reviews each diff on its own merits before anything touches the shared branch. The critical detail, easy to lose in the excitement about running several agents at once, is that review happens per agent and merge does not. Nobody merges four agents’ work into one branch and resolves the resulting mess; they read four independent diffs and take the one that actually solved the problem.

• Each agent gets its own worktree and branch, isolated from every other agent’s concurrent edits to the same files.
• Each agent produces a complete, reviewable diff against the shared base branch — not a partial edit waiting on another agent.
• A human or a judge model reviews each diff independently, on its own merits, without needing to reconcile it against the others.
• Only the winning diff — or the small subset worth keeping — gets merged. The rest are discarded or preserved unmerged, not force-combined.

This is a deliberately narrower claim than “run more agents and get more done.” The multiplier is not in the number of agents; it is in being able to throw away three-quarters of their output cheaply, because a rejected diff in an unmerged worktree costs nothing but the compute it took to generate. That is a different economic bet than the one this volume’s Chapter 4 examined in the orchestrator-worker pattern, where a lead agent decomposes one task into pieces that all have to come back together — here, several agents attempt variations of the same or related work, and the coordination cost is concentrated entirely in review, not in getting the pieces to fit.

How many agents is too many

It would be convenient to say a specific number, and precise-sounding numbers circulate freely in practitioner writing about this topic. They do not agree with each other, and none of them rest on anything more rigorous than one engineer’s or one team’s own experience running the workflow for a few weeks. Worth stating plainly: there is no controlled study behind any of the ranges below, and this chapter will not manufacture the appearance of one by picking a single figure and presenting it as settled.

What exists instead is a cluster of anecdotal reports that disagree by more than two-to-one. One widely read engineer’s post put his personal ceiling at three to four concurrent threads, attributing the limit to cognitive bandwidth rather than agent capability — the argument being that supervision, trust, and integration do not parallelize even when the agents themselves do, and that a comparable account from another practitioner described four agents running at once as enough to leave him “wiped out for the day.” A team building tooling around parallel agent workflows reports five to seven concurrent agents as comfortable on a modern laptop, with an explicit recommendation to start at two to three until the review workflow itself feels manageable, warning that scaling to ten before a team can review at that speed just creates a backlog. A third source, writing to promote a coordination tool, puts the sweet spot at three to eight and argues review becomes the binding constraint past that point regardless of tooling quality.

The one genuinely useful data point that is not an anecdote comes from Claude Code’s own tooling, and it cuts the other way. The `/batch` skill, built specifically for large mechanical changes, deliberately splits work across five to thirty worktree-isolated subagents, each of which opens its own pull request. That is not a contradiction of the smaller numbers above — it is a different point on the same curve. A batch of thirty agents making a mechanical, low-risk change and each opening a normal pull request distributes the review burden across the team’s ordinary PR queue over days. Three or four agents attempting genuinely different approaches to one ambiguous problem concentrate the review burden on one person, right now, trying to hold four unfinished mental models in their head at once. The number that matters is not agent count in the abstract; it is how much undistributed, synchronous review one agent’s output demands, multiplied by how many agents are asking for it at the same time. Framed that way, the qualitative shape of the claim — that review capacity, not agent throughput, is what caps parallelism — is well supported even though no specific number in the “3 to 10” range that circulates informally has real evidence behind it.

Five shapes of coordination

Isolated worktrees and a review-the-diffs workflow answer the mechanical question of how agents avoid stepping on each other. They do not answer the separate question of how work gets divided among agents in the first place, which is a coordination-topology question, not a filesystem one. Industry writing on multi-agent systems names several recurring topologies — orchestrator-worker, sequential pipelines, fan-out/fan-in, and swarm all appear, under varying labels, across independent accounts of how these systems get built. No single naming convention has settled; the underlying shapes recur more consistently than the words used for them. The table below is this chapter’s own organizing lens on that same underlying territory, not a citation of an external standard — five shapes, ordered roughly by how much central control they retain and how much review burden they concentrate in one place.

The shapes are not ranked by sophistication. Solo is correct for most work, including most work that involves an agent; reaching for parallelism by default is the same ceremony failure this Library has warned against elsewhere, applied to a new axis. Parallel workers is the shape this chapter has mostly described — the worktree-and-review-the-diffs pattern — and it is the shape with the cleanest failure mode, because independent tasks fail independently. Pipeline trades that independence for depth: it is the right shape when a task genuinely has sequential stages — draft, then verify, then document — but a pipeline concentrates risk at every handoff, since a downstream agent has no way to know a stage it trusted was wrong. Hub-and-spoke is the coordinated version of parallel workers, useful when the pieces are not actually independent and something has to hold the plan; it trades the clean failure mode of parallel workers for a single point where reconciliation can go wrong. Swarm is the least controlled of the five and, on current evidence, the least production-ready — the honest description of most swarm systems today is exploratory rather than load-bearing, useful for open-ended search over a solution space where no single correct decomposition exists, and risky wherever a wrong or duplicated action has a real cost.

Arena: parallel agents, one merge

Operon’s own implementation of the parallel-workers shape is a feature called Arena, and it is worth describing plainly because it is a concrete, shipped instance of exactly the workflow this chapter has been describing rather than a hypothetical. A user gives Arena one goal and picks two to four agents; each agent is spawned into its own pooled worktree — a warm, pre-provisioned worktree rather than one created fresh per run, to cut the setup latency of the isolation itself — and works the goal independently, with no communication between the agents. When every agent’s session reaches a terminal state, Arena computes a verdict per agent from data the rest of the system already collects for other reasons: cost, files touched, diff-quality score, scope violations, and tool success rate, plus an optional advisory recommendation from a judge model that looks at those same signals and never sees the other agents’ raw diffs. A human still makes the actual call — the winner field is write-once specifically so the pick cannot be silently overridden later. Picking a winner ends every other agent’s session, but the worktree teardown for the losers is deliberately non-destructive: uncommitted work is preserved, not discarded, on the theory that a losing agent’s output might still be worth a look even after it stopped being the one getting merged.

Two things about Arena are worth pulling out because they generalize beyond this one feature. First, the judging signals are all things the system was already recording for single-agent sessions — cost, diff quality, scope violations — which is the correct way to build a multi-agent judge: not a new evaluation apparatus, but the same instrumentation a single agent’s work would be checked against anyway, applied N times and compared. Second, ending the losing sessions without destroying their work is the same instinct this Library’s Volume V argued for under recoverable failure more generally — a losing diff in a preserved worktree is a cheap insurance policy against the judge, human or model, having picked wrong.