You split a big job across three or four coding-agent sessions so it finishes sooner. Each one does good work on its own. Then the trouble starts in the gaps between them: a merge conflict in a file none of them meant to share, an instruction you gave one agent that it never received, a test run that dies for lack of memory because two heavy jobs started at once. Whether to run the agents as equal peers or put one in charge comes down to four checks you can make before you start.
Table of Contents
What goes wrong when parallel coding agents work as peers
The failures don’t show up inside any one agent. Each session passes its own tests and writes a sensible report. They show up where the sessions meet. On one test project (a data pipeline with a production database, run on a 16 GB laptop, with five agent sessions over two days) every one of these happened:
| Symptom | What actually happened |
|---|---|
| A branch that passed its tests would not merge | Another agent merged first, and both had edited the same three shared files: a status document, the command reference and the command-line entry point |
| An instruction “sent” to an agent was never acted on | Both messages queued behind a busy agent’s turn were silently dropped; every message sent to an idle agent arrived |
| An agent said “merging as soon as the lock clears” | Its turn ended there, and nothing was merged until someone asked again |
| Tests failed with “the paging file is too small” | Two memory-heavy jobs ran at once; one at a time, the same tests passed |
| Production was written from an unmerged branch | The agent had approval in its own chat; nothing broke, but the rule “only merged code touches production” had nobody holding it |
| One more agent to keep track of | A worker started a worker of its own |
None of these is a bug in an agent. Each one is a coordination gap, and the four checks below ask whether your project has it.
Every agent can be right on its own and the project can still be wrong where they meet.
Changelog, status page, command list, entry point. Yes: the coordinator owns them and merges in order.
Memory, a database, a rate-limited service. Yes: one queue for the heavy jobs.
Work that keeps stopping to ask you. Yes: answer in one place, recorded with the date.
Can't confirm delivery: check the receiver's next commit, resend if missing.
All four clear: run as peers. Any yes: one coordinator, workers still in parallel.
Check 1: do the agents edit the same files?
Look for files every change touches: a changelog, a status or architecture page, a command list, a routing table, the main entry point of a command-line tool. Peers each add their line, and each branch is correct alone. Whichever merges second hits a conflict, and resolving it needs someone who understands both changes.
Giving each agent its own checkout keeps their uncommitted work apart (a git worktree per parallel agent covers how, and the git worktree reference lists the commands). It does not stop two branches from editing the same lines. If several tasks have to touch the same shared files, give those files to the coordinator: workers leave them alone, and the coordinator updates them as it merges each branch, one at a time.
Check 2: do they share something scarce?
Count what the agents compete for, not just what they edit:
- Machine memory. On the test project, the document parser needed about 4.5 GB free. On Windows, running short shows up as a “paging file is too small” error, because the page file backs memory that RAM can’t hold. At 2.8 GB free it failed on every page; at 4.3 GB free, with another job running, three of five real-parser tests failed. Run one at a time, all five passed.
- A database. Two agents writing to the same production tables need an order, a backup before each write and one place that says yes.
- A rate-limited outside service. Two agents crawling the same host, or spending the same API quota, slow each other down or get both of them blocked with an HTTP 429 Too Many Requests reply.
Running in parallel buys nothing when the jobs queue on the same resource anyway. A coordinator keeps one queue for the heavy jobs and lets the light ones run alongside.
Parallel agents only save time if they don’t queue for the same scarce resource.
Check 3: how often does the work need your decision?
Some work runs for hours untouched. Other work keeps stopping to ask: accept this result, pick an option, approve this write. With peers, each agent asks you in its own chat, and you become the switchboard. The answers end up scattered across conversations, and an agent may act on an answer meant for another.
With a coordinator you answer in one place. It passes each decision to the worker that needs it, quoting your words, and records it in the repository with the date. A decision recorded in the repository survives whichever session took it.
Check 4: can you tell a message arrived?
Agents that talk to each other through a messaging layer depend on delivery. On the test project, a message to an idle agent was delivered at once. A message sent while the agent was mid-turn came back “queued”, and both of those were lost. One was a decision a worker was about to act without. It was caught only because the coordinator read the worker’s next commit, saw the decision missing and sent it again.
So “queued” never means delivered. Check the receiving agent’s transcript or its next commit for the message, and resend it, marked as a resend, if it isn’t there. With peers, nobody does that check. With a coordinator, it is part of the job.
A queued message is a hope, not a delivery; check the receiver’s next commit.
Peers or a coordinator: the decision table
| Your project | Run as peers | Put one coordinator in charge |
|---|---|---|
| Independent units, each in its own files (separate articles, one adapter per data source, batches by customer) | Yes: little to collide, tidy up afterwards | Overhead with little gain |
| Shared files every change touches | Conflicts at merge time | Yes: the coordinator merges in order |
| A scarce shared resource (memory, a database, an outside host, a quota) | Agents compete and fail | Yes: one queue |
| Frequent decisions from you | You become the switchboard | Yes: one place to answer |
| Steps that depend on each other’s results | Agents wait on each other blindly | Yes: the coordinator orders them |
If your project lands in any row on the right, the coordinator usually pays for itself.
What the coordinator does
A coordinator is an ordinary agent session with a narrower job. On the test project, six rules covered it:
- It holds the plan and takes your decisions. Workers report to it. It passes each decision on and records it with your words and the date.
- It does every merge, one at a time, and runs the full test suite on the merged result before moving the main branch. Workers never merge their own branches.
- It approves every production write. Only merged code writes to production, after a backup that has been checked to restore.
- It owns the shared files and updates them as it merges, so workers don’t collide in them.
- It runs the heavy jobs one at a time and checks free memory before starting one.
- It checks, never trusts. A worker’s report is a claim. The coordinator reads the commit, the test output or the row counts before it tells you something is done, and confirms that every message it sent arrived.
Workers still run in parallel on their own steps. Two smaller rules help: workers don’t start workers of their own (they ask the coordinator), and side tasks inside a step (a search, a review, a check) go to short-lived helpers that report back into that step, not to more full sessions you have to follow.
When peers are the better choice
A coordinator costs something: one more session, and a relay step for every decision. When the work splits cleanly (each agent writes its own article, each handles one data source and nothing reaches production until you review it) peers finish sooner and the overhead buys nothing. Tidy up the branches at the end and you’re done.
The other case is a fixed bulk job, the same check run on thousands of items. Use a script that fans the items out to helpers and collects the results (one agent can also supervise another for jobs like this). It doesn’t need a coordinator holding context, because nothing in the job waits on a decision.
The short version
Run parallel coding agents as peers only when they work in separate files, share nothing scarce and rarely need you. Otherwise put one coordinator in charge of the plan, your decisions, the merges, the production writes, the shared files and the queue of heavy jobs, and let the workers do the work. Whichever you choose, treat every agent’s report as a claim to check, and never assume a queued message arrived. Long sessions also degrade on their own, which keeping the context window as a budget addresses.
Frequently Asked Questions
Isn’t a coordinator just a bottleneck?
Only for the things that must happen one at a time anyway: merges, production writes and memory-heavy jobs. Those were already serial; the coordinator just makes the order deliberate. Everything else still runs in parallel in the workers.
Can the workers merge their own branches if the tests pass?
A worker’s tests prove its branch alone. Once another branch has merged, the combination is untested. The coordinator merges each branch into the current main and reruns the full suite on the result, which catches the conflicts and interactions no single worker can see.
What should I do when a message to an agent seems lost?
Search the receiving agent’s transcript for a distinctive phrase from the message, or read its next commit. If it isn’t there, resend it, say it is a resend, and repeat any decision word for word. Where you can, send while the agent is idle rather than mid-turn.