Why multi-agent coding fails, and the four fixes

what failure actually looks like

Multi-agent coding fails in four recognisable ways, and none of them announce themselves as failures at the time: agents overwrite each other in a shared checkout, their contexts drift apart until two of them believe different things about the same code, the review queue outgrows the one person reading it, and spend accumulates where nobody is looking. Three of the four have fixes that are structural, old and slightly boring. The fourth, review, does not have a fix, and being honest about that is the point of this post.

What makes them difficult is not that they are subtle in retrospect. They are all obvious in retrospect. It is that each is invisible while it happens and only takes shape hours later, in a branch that lost an afternoon, a diff you approved without reading, or a bill. The arithmetic that makes people reach for a second agent is real. All four are ways that arithmetic quietly stops holding.

Deliberately not in the list: "the model was not good enough." That is a single-agent failure experienced several times at once. Everything below exists only because there is more than one.

failure one: they overwrite each other

Two agents in one working directory are two processes writing the same files with nothing between them. Agent A reads a file, thinks for forty seconds, and writes back a version assembled from what it read at the start. Agent B's edit, made during those forty seconds, is gone.

This is worse than it sounds because it is not a merge conflict. A conflict is git telling you two changes disagree and refusing to guess. This is a lost update: as far as git is concerned exactly one write happened and it succeeded. No marker, no warning, no failed command. You find out when a test fails for a reason that makes no sense.

The fix, which is older than agents

Give every agent its own checkout. In git that is a worktree, which is cheap because all of them share one object database, so several checkouts of a large repository cost far less disk than several clones would.

git worktree add ../wt-api    -b agent/api
git worktree add ../wt-schema -b agent/schema
git worktree list

# each agent is launched with its own path as cwd,
# so it cannot write into anyone else's tree.

# later, once the branch has landed
git worktree remove ../wt-api

This does not buy the absence of conflict. Two agents editing related code still produce changes that disagree. It buys the conflict surfacing at merge time, where git reports it and a human is already looking. A failure that announces itself is a different category of problem. The worktree post covers the layout, the cleanup and the ways this still bites.

failure two: their contexts drift apart

Each agent has its own context window and none can see any other's. That is not a bug; it is what makes parallelism possible. It becomes a failure when the agents need to agree about something and have no mechanism for agreeing.

The recognisable version: agent A spends twenty minutes discovering that the auth middleware is generated from a schema file and must not be hand-edited. Agent B, on the API layer, hand-edits it. Both are behaving correctly given what they know. The knowledge never crossed, because context does not flow between sessions unless something makes it flow.

The subtler version is drift in the plan rather than in the facts. Two agents given the same task description interpret the ambiguous parts differently, and both interpretations are defensible. You get an API returning one shape and a UI expecting another, and neither diff is wrong on its own.

The fix: put the shared beliefs in the repository

The mechanism that works is unglamorous. Whatever the agents must agree about goes into a file, in the repo, on the branch, before any of them start:

• A plan file. The decomposition, the interfaces, the merge order. Reviewed by you and committed before the fleet starts.
• The interface, concretely. Not "the API returns the user" but the actual type. Ambiguity in a shared boundary is where drift enters, and a type declaration is the cheapest way to close it.
• Discoveries, appended. When an agent learns something that changes another agent's work, that is a commit to the plan file, not a fact living in one context window until the next restart.

Pasting one agent's output into another's prompt also works and is what most people do. It is manual and lossy and does not survive a restart, but it is not wrong. A file is simply still there tomorrow, and still there for the agent you spawn at four o'clock who was not around for the conversation. A worked example is in building a full-stack app with three agents.

What does not fix this is prompting harder. A longer system prompt cannot transmit a fact learned after the prompt was written. It is a plumbing problem wearing the costume of a prompting problem, which is why it survives so many attempts at better instructions.

failure three: the review queue outruns you, and nobody has fixed this

Agents parallelise. Review does not. Every agent you add produces another diff one person has to read, another set of judgement calls one person has to make, and another moment where work stops and waits for that person. Four agents do not give you four times the throughput; they give you four times the output arriving at a reviewer whose rate is fixed.

The failure is not that the queue gets long. A long queue is visible and you can stop starting things. The failure is what a long queue does to the reading. Past some number of diffs, people stop reviewing and start pattern matching: the shape looks familiar, the tests pass, the summary sounds right, approve. From the inside that is indistinguishable from reviewing. It feels like reading. And it is the mechanism by which a multi-agent setup produces worse code than one careful session while appearing to produce more of it.

What genuinely helps, without solving it

• A second model reading the diff cold. A reviewer that did not write the code disagrees with it in ways the author cannot, because it never held the reasoning that produced it. It catches a real fraction before you see it, and misses the things that require knowing what the feature was for. How to wire one is a post of its own.
• Knowing which agent is waiting on you. A finished agent, an agent mid-thought and an agent sitting on a permission prompt for eleven minutes look identical in a terminal you are not looking at. Surfacing blocked agents does not shorten the queue, it stops you spending review capacity on polling.
• Smaller units of work. Four narrow tasks produce four small diffs, collectively easier to read than one large one. Same advice as for human pull requests, same reason.
• Merge order decided before starting. Reading diffs in dependency order costs less than reading them in arrival order.

The honest conclusion is a constraint rather than a technique: the number of agents you should run is set by your review capacity, not by your machine. If that number is two, run two. Running six and approving four unread is not six agents of throughput, it is two plus four agents of unreviewed code in your repository.

failure four: spend nobody is watching

One agent in a terminal gives you no running total. Four agents give you four times no running total, at a combined rate nobody watching four scrollbacks can estimate.

Two things make this specifically a multi-agent failure. First, burn rate multiplies while attention does not: the moment the money matters most, several agents running unattended while you do something else, is exactly the moment nobody is looking. Second, the arithmetic is not intuitive even when you do look. Fresh input, cache writes, cache reads and output are billed at different rates, and in a long coding session the great majority of tokens are cache reads. Summing them into one count and pricing it at the input rate is wrong by a multiple, which we measured in what Claude Code actually costs.

The fix is visibility before it is limits

The instinct is to reach for a cap. Caps have their place, but the more effective control is a per-agent running total always in front of you without you asking. Most overspend is not a runaway loop a threshold would have caught. It is four agents doing somewhat more work than you assumed for somewhat longer than you meant, which a visible number corrects long before any limit is near.

When you do add a limit, one distinction is worth stating plainly: a cap may only stop work somebody deliberately launched under that cap. Killing an agent a human was typing into leaves a half-written file and applies a consequence to work that never opted in. Meter everything, gate only what consented. Skribbl implements that split deliberately, and the reasoning is worked through in setting a token budget.

the shape all four share

Read together, the four share one property, and noticing it beats any individual fix.

None of them produce an error. Every one is a thing that goes wrong while everything continues to look like it is working, which is why they resist being fixed by attention or by care. You cannot pay closer attention to an event that emits no signal.

That is why every fix here is structural rather than behavioural. Separate checkouts require you to remember nothing. A plan file does not depend on you recalling what agent A discovered. A visible total does not need you to decide to check it. Each converts a silent failure into an impossibility or a visible event, and that conversion is the technique. A fix of the form "be careful about X" helps with none of these, because being careful requires knowing when to be. The topologies these play out inside are in what AI agent orchestration means.

so how many agents

The honest answer starts with what we do not know. We have no defensible number for how many agents a developer can run and have not measured one. Anybody quoting a figure is describing their own attention span, codebase and tolerance for unreviewed code. What can be said without inventing anything is a procedure.

• Start with one. If one agent works and you review its output properly, you have no problem to solve. Orchestration is worth as much as the bottleneck it removes.
• Add a second only when you can name the file boundary between them. If you cannot say which files each will touch, you are about to create failure one and blame the model.
• Stop where you notice yourself approving without reading. That moment is the real limit, it arrives earlier than people expect, and it is personal, which is why nobody else's number helps you.
• Re-derive it per task. Four agents applying one mechanical refactor is a different review load from four agents designing four features.

The setup mechanics, in order and with the commands, are in how to run AI coding agents in parallel. What to reach for when the tooling itself is the question is in the comparison page, which is deliberately explicit about what other tools do better.

common questions

Setting this up for the first time: start with the workspace setup guide, and read who may command whom before letting one agent instruct another. For the canvas shape of this, the download page says what it runs on and what it does not do.