How do I run several AI coding agents at the same time without them breaking each other’s work?
Two or three coding agents can work on one codebase at once without overwriting each other. Git worktrees, clear task borders, one rules file and tests before each merge, with the advice from the Claude Code, Codex and Cursor docs.
Give each agent its own copy of the code with a git worktree, and give each one a task with a clear border: one job, one part of the code, one test that proves it. Then merge their work one at a time, after the tests pass and a person has read the diff. Start with two agents, not ten.
I run a team of AI agents every day in my own Mac app, VShell. Every member works on one assignment at a time, in its own session, and reports back to a PM agent. Nobody pushes straight to main. For running multiple AI coding agents in parallel, the docs of Claude Code, Codex and Cursor now give much the same advice.
Four ways parallel coding agents break each other’s work
- Same filesTwo agents edit one folder and write over each other.Fix: own copy, a worktree
- Same idea, different guessesEach agent makes small choices that nobody wrote down.Fix: one rules file
- Same machineTwo dev servers want port 3000. Two test runs share one database.Fix: own port, own test database
- Same limitEvery agent draws from your one usage plan.Fix: two agents, not ten
Most clashes fall into one of these four boxes. Git helps with the first one. The other three need rules you set yourself.
Same files. Two agents edit one folder and overwrite each other. Even with separate branches, the merge can fail. In a July 2026 study of 33,596 agent pull requests, 40.2% of repositories had two agent pull requests open at the same time. When the researchers replayed the merges, 19.8% of pairs from the same agent had a conflict, and 41.7% of pairs from two different agents.
Same idea, different guesses. Each agent makes small choices that nobody wrote down. Walden Yan of Cognition gave the classic example: one subagent drew a Super Mario style background for a Flappy Bird clone, the other drew a bird that did not match, because neither could see what the other was doing.
Same machine. A worktree copies the code. It does not copy ports, databases or anything else outside git. Two dev servers want port 3000. Two test runs share one local database. One agent’s cp can still write into your main folder, and Claude Code’s docs say so plainly.
Same limit. Every agent draws from your plan. Claude Code subagents (helper agents that one session starts) count toward the same usage limit as your main session.
Give each agent its own copy of the code with git worktrees
- mainyours
main - agent-abilling
agent/billing - agent-bsearch
agent/search
.gitone shared history
One history. Separate files. Separate branches.
A git worktree is a second folder of the same repository, on its own branch. Git’s own docs: “A git repository can support multiple working trees, allowing you to check out more than one branch at a time”. Git also refuses to open one branch in two worktrees, which is a useful guard.
# plain git, works with any agent
git worktree add ../shop-billing -b agent/billing
git worktree add ../shop-search -b agent/search
# Claude Code makes one for you under .claude/worktrees/
claude --worktree billing
All three tools now build this in:
| Tool | How it isolates an agent | What to know |
|---|---|---|
| Claude Code | claude --worktree <name>; isolation: worktree for a subagent | Add .claude/worktrees/ to .gitignore. Agent teams do not get worktrees. |
| Codex | Worktree mode next to Local; managed worktrees in $CODEX_HOME/worktrees | Keeps your 15 most recent and saves a snapshot before it deletes one. |
| Cursor | A worktree per agent in the Agents Window; /apply-worktree brings changes back | Setup commands go in .cursor/worktrees.json. Up to 25 worktrees per machine by default. |
The step people skip is setup. A worktree is a fresh checkout, so it has no node_modules and no .env. Claude Code and Codex both read a .worktreeinclude file that copies gitignored files such as .env into each new worktree (Claude Code, Codex). For the “same machine” box, give each worktree its own port and its own test database name in that .env.
Split the work so each agent owns one part of the code
- src/
- billing/Agent A
- search/Agent B
- shared/
- tests/
- billing/Agent A
- search/Agent B
Hot files: one owner only
- package.json
- routes.ts
- db/migrations/
- config/
- CHANGELOG.md
A good parallel task owns a folder, not a feature that runs through every layer. Anthropic’s advice for its own multi-agent system was that each subagent needs “an objective, an output format, guidance on the tools and sources to use, and clear task boundaries”. Without them, “agents duplicate work, leave gaps”.
The hot-files shelf matters most. Package files, the router, migrations and shared config are where parallel branches collide. The 2026 study found that 84.4% of conflicted files were source code, and nearly 42% of conflicts were structural: one branch changed a file the other deleted, or both added the same file. Give each hot file to one agent, or make those changes yourself at the end.
Anthropic’s C compiler project shows the limit. Sixteen Claude agents worked in parallel for two weeks, each in its own container, and each claimed a task by writing a lock file. That worked while there were many separate failing tests. When the job became one big task, building the Linux kernel, every agent hit the same bug, and “Having 16 agents running didn’t help”. Parallel agents help only when the work really splits.
One rules file, one report, one merge at a time
- ✓tests green
- ▤report read
- ◉diff read by a person
- ↺rebase on main
- →merge into main
One car at a time
Every agent reads the same rules file, so they share the small choices: naming, error style, which library to use. That closes much of the “different guesses” box. How to keep that file short is in my article on a good CLAUDE.md.
Each agent ends its work with a short report. In my team it is three parts: what I did, the result, what is left. Ask for the files it touched and the test command it ran.
Then the merges go one at a time. Tests pass first; then a person reads the diff (the list of changed lines). After each merge, the next branch rebases on the new main, which means its changes move on top of the newest code, and it runs its tests again. This step catches two branches that each pass alone but break together.
Review is the slowest step. Simon Willison wrote that “the natural bottleneck on all of this is how fast I can review the results”. Faros AI’s 2026 data from 22,000 developers points the same way: on teams that use AI the most, pull requests were 51% larger and median review time was five times longer than on teams that use it least (vendor data). How I check AI code before it merges is in my article on checking AI code quality. Setting up this flow for a team’s agents is part of what my team does; here is how we work.
How many coding agents should I run at once?
How many agents developers runStack Overflow pulse survey, late April 2026, 1,100 developers and working professionals
Source: Stack Overflow, “Agents on a leash”, 27 May 2026. Shares as published; they add to 102% because of rounding.
- about 4×tokens: an agent vs a chatAnthropic, Jun 2025
- about 15×tokens: a multi-agent system vs a chatAnthropic, Jun 2025
- about 7×tokens: a Claude Code agent team in plan mode vs a normal sessionClaude Code docs
Two. Three if your review keeps up. This is my judgment, not a measured number: no neutral study I found measures how much each extra agent adds.
The surveys say most people are still at one. In Stack Overflow’s April 2026 pulse survey, 69% ran a single agent, 17% several specialised agents and 16% several coordinated ones. Mitchell Hashimoto said in February: “I’m not [yet?] running multiple agents, and currently don’t really want to”. Peter Steinberger wrote in 2025 that he runs “between 3-8 in parallel in a 3x3 terminal grid”.
Claude Code’s docs suggest 3 to 5 teammates for an agent team and add that “Three focused teammates often outperform five scattered ones”. Costs grow with every agent. Anthropic measured multi-agent systems at about 15 times the tokens of a chat, and an agent team in plan mode at about 7 times a normal session. VShell has a hard rule for this: no new session on an account above its usage threshold.
Parallel agents in 2025, 2026 and a guess for 2027
- Cursor 2.0Up to eight agents on one prompt, with worktrees.
- Codex appBuilt-in worktrees.
- 16 Claude agentsBuild a C compiler together.
- Cursor 3The Agents Window.
- Claude CodeFive ways to run agents in parallel; agent teams still experimental.
- My guessTwo or three agents is the normal setup.
- 2025. Running agents side by side was new. Cursor 2.0 added up to eight at once in October, and 31% of developers used agents at work at all.
- 2026. Agent use at work reached 59% in April. All three tools now have worktrees built in (Codex app, 2 February; Cursor 3, 2 April), and Anthropic ran 16 agents on one project.
- 2027 (my guess). Running two or three agents becomes the normal setup, and the tools merge more of the work for you. Review stays the slow part, so good tests will matter more than the number of agents.
Start with two agents tomorrow: a checklist
Agent A
- Task (one sentence)
- Owns these folders
- Must not touch
- Test that proves it
- Report: did / result / left
Agent B
- Task (one sentence)
- Owns these folders
- Must not touch
- Test that proves it
- Report: did / result / left
Same rules file. Merge one at a time.
- Pick two tasks that touch different folders, like a bug in billing and a new search filter.
- Make two worktrees, or
claude --worktreetwice. Copy.envand give each its own port. - Fill in one card per agent. Put “must not touch” in the prompt, with the hot files listed.
- Let both read the same
AGENTS.mdorCLAUDE.md. If you mix tools, read my article on which coding agent to use first, because two different agents clashed twice as often in the study. - When one finishes, read its report, run the tests, read the diff, merge.
- Rebase the second branch on main, run its tests again, then merge it.
- Remove both worktrees with
git worktree remove. Willison once lost a whole feature in a forgotten worktree.
Questions people ask
Is a git worktree the same as a branch?
No. A branch is a line of history. A worktree is a folder on disk where one branch is checked out. One folder has one branch checked out at a time, so two agents in one folder always edit the same files.
Can two agents work on the same file?
Not at the same time. Claude Code’s agent team docs say it directly: “Two teammates editing the same file leads to overwrites”. Do those edits one after the other, in one agent.
Do Claude Code agent teams use worktrees?
Not by default. Teammates share one folder, so the docs ask you to split the work so each teammate owns different files. Agent teams are still experimental and off by default. For edits in parallel, separate sessions with --worktree are the safer start.
Does running more agents cost more?
Yes, roughly in line with the number of agents. Each one has its own context window (the text the model holds in mind at once) and its own token use, and on a Claude plan all of them draw from one usage pool (Claude Code costs).
If you want coding agents set up for your team, working side by side with real checks, see how I can help or tell me about your project.
Have an app idea, a stuck app, or a daily job you want an AI agent to do?
Write three lines. I reply within one working day with a plain answer.
Sources. Claude Code docs: Run agents in parallel, Worktrees, Agent teams, Costs, Common workflows, Subagents (read 23 Oct 2026); Claude pricing page. Git documentation, git-worktree (2.56.0). Codex docs, Worktrees. Cursor docs, Worktrees (Cursor 3.5). Cursor changelog 2.0 (29 Oct 2025) and 3.0 (2 Apr 2026). Codex changelog (2 Feb 2026). Anthropic Engineering: “Building a C compiler with a team of parallel Claudes” (Nicholas Carlini, 5 Feb 2026), “How we built our multi-agent research system” (13 Jun 2025). Cognition, “Don’t Build Multi-Agents” (Walden Yan, 12 Jun 2025). Xu, Subramanian and Karthik, arXiv 2607.04697 (6 Jul 2026). Stack Overflow, “Agents on a leash” (27 May 2026). Faros AI, AI Engineering Report Q2 2026 (vendor). Simon Willison (5 Oct 2025; 19 Feb 2026). Mitchell Hashimoto (5 Feb 2026). Peter Steinberger, “Just talk to it” (2025).


