Development

Running several Claude Code agents in parallel: what works, what breaks

· founder of ETCSEC · updated November 9, 2026 · 6 min
The short answer

To have several Claude Code agents work at the same time, give each one its own git worktree and branch. Beyond three or four agents, the real problems are file conflicts, review and cost: you need one ticket per agent, a file scope and a review before merge.

Why parallelize, and what breaks starting with the second agent

A human development team almost never works with a single engineer at a time on an active project: several people make progress in parallel on different parts of the same repository, with a system of branches, review and integration that has been refined for this purpose for years. The same logic applies to Claude Code agents: in principle, nothing prevents several agents from working on the same project at the same time, as long as each one stays within its own scope, the same way you would expect a human engineer not to touch a colleague's module without prior coordination.

Running a single Claude Code agent at a time has a simple limit: the total time stays the sum of each task's time, even when several tasks have strictly nothing in common. Translating an article into six languages, fixing a server-side bug while fleshing out a documentation page, or advancing three independent tickets from the same work item are all cases where nothing requires waiting for one agent to finish before launching the next. Parallelizing several Claude Code agents, whether through sub-agents in a single session, coordinated agent teams, or independent sessions in separate worktrees, promises to bring that total time down to the duration of the longest task rather than the sum of all the tasks.

Launching several agents in parallel is almost never the problem: any terminal can open several Claude Code sessions within seconds. The problems start as soon as two agents touch, even briefly, some shared state, whether that is a file, a branch, a local server port, or a review budget already occupied elsewhere. Four symptoms tend to recur, roughly in this order as the number of agents increases.

The first symptom is file conflicts: two agents modifying the same file at the same time, in the same working directory, almost always end up overwriting part of each other's work, especially when neither rereads the latest state before committing. The risk grows further when the two agents share the same Git working directory, meaning each one sees, at the same moment, the other's uncommitted changes, well before either has been able to validate them.

The second symptom is lost context: an agent that picks a task back up after another agent has modified a neighboring file sometimes works on a version of the code that no longer exists, because its own conversation context was never informed of the change. This mismatch does not always produce an immediately visible error; it often produces code that compiles, that looks correct locally, but that contradicts a decision made in the meantime by a neighboring agent on the same file or on a file that depends on it.

The third symptom is review saturation: every additional agent produces an additional diff to review, and review does not parallelize as easily as writing, because it requires human attention or automated review whose capacity stays roughly fixed. According to a CodeRabbit study reported by The Register in December 2025, AI co-written pull requests contain 1.7 times more issues than pull requests written without assistance: multiplying agents without multiplying review capacity amounts to accumulating a debt that only becomes visible at integration time.

The fourth symptom is cost, which climbs faster than the number of agents rather than at the same pace: each agent rebuilds part of its own context in every session, each conflict resolved after the fact consumes tokens again to reread and fix, and poorly framed coordination between agents adds back-and-forth that would not exist with a single agent. Claude Code's documentation on managing costs recommends, for this precise reason, framing the scope of each session before launching it rather than letting it grow over the course of the conversation.

These four symptoms are not arguments against parallelization itself: they simply indicate that beyond one agent, the coordination work does not disappear, it shifts from writing code to defining scope, criteria and review. The next section details, step by step, how to set this framework before launching the second agent rather than after noticing the first conflict.

Project overview in Atipol: agents by status, two agent leads
Several agents in parallel, by status: working, in review, blocked, with their agent leads.

Step-by-step method to stay in control

Five practices cover most of the symptoms described above. None depends on a particular tool: they apply just as well to sub-agents within a single session as to independent sessions launched in separate worktrees. They come in this order, because each one reduces a risk that the next one can no longer fully fix once it has happened.

The first practice is a Git worktree and a branch per agent. The git worktree add command creates a separate working directory, with its own file state, while sharing the same Git history as the main repository: two agents set up in two different worktrees can no longer, by construction, see or overwrite each other's uncommitted files, even if they work on the same repository at the same time. Claude Code's documentation on common workflows describes exactly this pattern for running several sessions in parallel without them stepping on each other, with each session staying on its own branch until an explicit merge brings the work back together. An agent that finishes its task leaves behind a branch ready for review, which integration can accept or reject without ever having touched the working directory of the agents still in progress.

The second practice is a file scope defined per task, before the agent starts writing. A ticket that specifies exactly which files or folders an agent is allowed to modify removes a good part of the conflict risk before it even happens, since two agents whose scopes do not overlap cannot, by definition, write to the same file. This scope should stay narrower than what the agent's general role would normally allow, because it is the ticket at hand, not the agent's role, that determines what a specific task actually needs. A scope that is too broad, even with good intentions, amounts to giving agents back the same exposure as a single agent with no breakdown at all, only spread across several sessions instead of concentrated in one.

The third practice is writing the acceptance criteria before launching the agent, not after reading its delivery. A criterion written in advance, such as "the build command passes" or "the five translations cover the same sections," gives the agent a verifiable target and gives its reviewer an objective test rather than a general impression of how good the result is. Without a prior criterion, review drifts toward a case-by-case judgment call, which quickly becomes inconsistent from one agent to another and from one task to another. This same criterion also serves as a stopping point: an agent that cannot satisfy it signals a blocker before review, rather than delivering an approximate result hoping it goes unnoticed.

The fourth practice is review before any integration, never after. A diff reviewed before merging can still be corrected without affecting other agents' work; a diff merged first and reviewed afterward forces you to undo an already shared history, with the risk of removing, in the process, valid work done in the meantime by a neighboring agent on a file that depends on it. Review must cover the actual diff, not just the summary the agent provides of its own work, precisely because an optimistic summary does not always reveal an acceptance criterion that was left unmet. This discipline costs a bit of time on every delivery, but it always costs less than untangling, after a merge, which of two agents produced which part of the same file.

The fifth practice is limiting the number of simultaneous sessions to what review can actually absorb. Claude Code's documentation on sub-agents and agent teams recommends starting with three to five teammates before considering going further, noting that two agents on the same file almost always produce an overwrite rather than a clean merge. This number is not a technical limit of the protocol; it is a practical limit on what a reviewer, human or automated, can seriously check before integrating. Raising this number remains possible later, once file scope, acceptance criteria and review before merge are already working smoothly on a small number of agents.

Table of pitfalls and fixes

The table below lists the most common pitfalls observed beyond two agents, with their concrete symptom and the fix that avoids it; each fix maps directly to one of the five practices from the previous section.

PitfallSymptomFix
Two agents on the same filePart of the work gets overwritten before commit or at mergeA worktree and a branch per agent
Unclear task scopeTwo agents modify overlapping files without knowing itA file scope written into the ticket before launch
Missing acceptance criteriaThe delivery looks finished but does not meet the actual requestAcceptance criteria written before the agent is launched
Merge before reviewA flaw found afterward forces you to undo shared historyA review of the actual diff before any integration
Too many sessions at onceReview gets swamped and code debt builds up unnoticedA number of simultaneous sessions limited to what review can absorb
Context not shared between agentsAn agent works on a version of the code already changed by anotherOne ticket per agent with its own scope, reviewed before merge

How Atipol handles it

In Atipol, each agent works in its own Git worktree, on its own branch: two agents never modify the same files at the same time, by construction rather than by individual discipline. Each ticket reserves a file scope before the agent starts writing, and two tickets in progress cannot reserve the same scope: the risk of overwriting between two agents is removed before the first commit rather than at merge time. This reservation is checked at the very moment the ticket is handed to an agent, not after the fact during an end-of-week review, which prevents an overlap from being discovered only after both agents have already written to the same lines.

Every ticket requires acceptance criteria written before the agent is launched, which prevents a task from finishing without anyone knowing exactly what needed to be true to consider it done. The project's agent lead reviews every delivery before integrating it, and this integration reruns the project's checks rather than relying solely on the review that preceded it. This review covers the actual diff produced by the agent, and the integration that follows does not simply trust the reviewer's opinion: it reruns the project's own checks itself, so that an oversight in review does not become a silent flaw in the main branch.

The number of simultaneous sessions is set at the project level, so that review load and token cost stay under the team's control rather than growing with however many agents one could launch. This setting stays in the hands of the team running the project, not a parameter fixed once and for all by the platform itself. Atipol is not limited to Claude Code: the same framework of tickets, file scope and review before integration applies to other development agents.

Tree org chart in Atipol: people, agent leads, agents and sub-agents
Who runs what: each person has their own agent lead, which coordinates its agents and their sub-agents.

Frequently asked questions

Do you need a worktree for every Claude Code agent?

As soon as two agents touch the same repository at the same time, yes: a worktree and a branch per agent remove the risk of file conflicts at the root instead of handling it after the fact.

How many agents can you run in parallel?

As many as there are genuinely independent tasks. The real limit is not the number of sessions you can open, but the review capacity and budget available to check them.

What if two agents need to touch the same file?

Sequence them instead of parallelizing on that specific file, or split the task so each agent gets a distinct file scope before starting.

Does a sub-agent replace a separate worktree?

No: a sub-agent stays within the same session and context, for a short side task. A separate worktree is for long, independent work, on its own branch.

How do you keep review from becoming the bottleneck?

By limiting the number of simultaneous sessions to what a reviewer can seriously check, and by writing acceptance criteria before launch rather than after delivery.

How does Atipol prevent two agents from reserving the same scope?

Each ticket reserves a file scope before the agent starts writing, and two tickets in progress cannot reserve the same scope: the conflict is ruled out before the first commit.

Sources

To connect this method to a complete governance framework, see our AI agent governance guide.

For what these parallel agents cost in practice, see our article on AI agent costs.

Try it on a real project

The public demo shows a fictional organization at work, no account needed. The free plan includes a project, three agents and an agent lead.