Parallel Sub-Agents in Claude Code: Partition by File First

Twenty sub-agents can run at once in a Claude Code session by default, and spawning that many feels like free parallelism. Type the dispatch, four windows open, wait for four reports. The sub-agents post covered why the dispatch itself pays off: a scoped task gets its own context window, and only the conclusion comes back into mine. It didn’t cover what happens once more than one of those sessions is running at the same time.

The documented failure doesn’t look like a collision. It looks like nothing happening. One agent ends up holding six items from the work queue while three others sit idle, because every item that came up got routed to whichever agent already owned the file in front of it, on reflex. Two of those six items lived in files none of the idle agents’ teammates were touching. The queue backed up on one agent instead of splitting across four, and the fan-out that was supposed to save time spent most of it waiting on a single chain.

The System

Publishing the partition before anyone spawns, not after the first collision, is what actually stops the queue from backing up on one agent.

Before dispatch, every file or glob in the work gets an owner, one agent per partition, and the map goes out with the brief instead of getting improvised once two agents show up in the same place. An agent that needs a change outside its own partition doesn’t make it. It reports needs_human, names the file, and waits for the partition to get redrawn around it. That’s a slower path than just fixing the file itself, and that’s the point. A silent cross-write is what turns four independent tasks into four agents fighting over the same lines.

When two items genuinely need the same file, a shared config both workers have to touch, worktree isolation gives each agent its own working copy so edits land without clobbering each other, reconciled on merge instead of mid-flight. Worktrees solve the collision. The ownership map is what stops the routing mistake that makes worktrees necessary in the first place: sending the second item’s work to whichever agent is idle instead of to the agent that already owns its file.

None of this grows its own hierarchy. Orchestrator to workers, two levels, and a worker doesn’t spawn workers of its own to cover a queue that’s backing up. An agent that discovers it needs help reports back and waits for the level above it to decide, rather than quietly recruiting another agent underneath itself. The one sanctioned exception is research, a role built specifically to dispatch its own explorers and synthesize what comes back. Everyone else stays two levels deep.

What Fanning Out Buys

The reason to split a queue by file at all is wall clock. Four independent chains, each with its own file and its own agent, run at the same time instead of end to end, so the batch takes as long as the slowest single chain instead of the sum of all four. That’s the payoff, and it only shows up if the partition holds. An agent sitting idle because nothing was routed to it is spending nothing and saving nothing, just holding a seat while the queue backs up somewhere else.

The honest half doesn’t get softer just because the partition is clean. Fanning four workers out can still cost more in aggregate, in tokens spent, than doing the same work serially in one session, because each of those four sessions pays its own setup cost before it writes a line. A clean partition stops agents from colliding. It doesn’t make the fan-out free.

And a clean partition doesn’t mean every item belongs in one. Spawning an agent to cover a two-file edit buys nothing while it’s still paying for a cold context, reading in everything it needs to know from scratch before it can start. That’s true whether those two files have one owner or two. The partition tells you who owns what once the fan-out is already decided. It doesn’t decide the fan-out for you.

Try It Yourself

The friction is that partitioning ahead of time means knowing, before any work starts, which files each item actually touches, and not every item maps cleanly onto one. A design decision, a question that needs answering before any code gets written, an item that legitimately spans three files nobody wants to hand off in pieces. Those don’t belong in a partition. They get named and handled before the fan-out starts, not discovered mid-run when two agents turn up in the same file.

Here’s a prompt that works out the partition before anything spawns, including naming what won’t split cleanly:

A partition published before the first agent spawns is the difference between four chains running at once and one agent working through everybody else’s queue.