How to Run 10+ Parallel Claude Code Agents Without Merge Conflicts

Running one AI coding agent is easy. Running ten on the same repository at the same time is a distributed-systems problem in disguise, and the first thing you lose is your own committed work.

The naive setup looks fine for an afternoon: open several terminal tabs, start an agent in each, point them at different features. Then two agents edit the same file, a third rebases onto a stale local branch, and an hour of work silently disappears on the next push. Nothing crashes. There is no error. The commit history just quietly drops changes, because each agent assumed it had the latest code and none of them did.

The root cause is shared mutable state. A single git working directory, a single local main branch, and a single browser profile are all singletons. The moment two agents touch one of them concurrently, you get a race condition with no lock.

This guide is the protocol we run in production to keep a fleet of agents productive without stepping on each other. It has three pillars: isolate the filesystem with worktrees, isolate side effects like browsers per agent, and enforce a strict sync-before-edit and merge-after-commit discipline. Every rule below exists because skipping it cost us real work.

Before any tooling, name the shared resources. In our stack there are exactly three that bite:

1. The working tree + local main. If every agent commits to the same local main, the last push wins and everything else is overwritten.
2. The browser used for testing. Chrome locks its profile directory. Two agents pointing at the same profile collide on session locks, cookies, and debug ports.
3. Monolithic shared-state source files. We have one ~10,000-line component, components/admin/studio/PromptEditorPanel.tsx, that holds four tab UIs in a single state block. Two agents editing it simultaneously guarantees a merge conflict and a silent reversion.

Every rule in this guide maps back to isolating one of these three. If you remember nothing else: filesystem, side effects, and hotspot files each need a strategy.

A git worktree is a second checkout of the same repository, on its own branch, in its own directory, sharing one .git database. It is the cleanest way to give each agent its own filesystem without cloning the repo ten times.

Each agent gets a worktree under a predictable path. The agent works, commits, and tests entirely inside its own directory. Two agents editing lib/foo.ts no longer collide, because each has its own copy on its own branch. They only meet when their work merges back to main.

The discipline that makes this safe is a single mandatory script run from inside the worktree after every commit:

# Run from the worktree directory, after committing
./.claude/scripts/merge-to-main.sh

That one command does the whole dance: it fetches origin, rebases the branch onto origin/main, fast-forward merges into local main, pushes to origin/main, then deletes the branch and removes the worktree. The rule we enforce is absolute: do not end a session without running it. An unmerged worktree commit is invisible to every other agent, and the next agent that merges will silently overwrite it.

This is the rule that looks redundant and is not. Before editing in any worktree:

git fetch origin && git rebase origin/main

Note origin/main, not main. Rebasing onto local main only syncs you to whatever your machine last pulled, which in a ten-agent fleet may be hours behind. We have watched git rebase main quietly revert another agent's merged work because local main was stale. The remote is the only source of truth when multiple agents share a repo. Fetch it explicitly, every time, before the first edit.

The symmetric rule applies after merging: the instant a worktree merges into local main, push to origin/main. The window between "merged locally" and "pushed" is exactly when another agent can fetch a tree that's missing your work. Keep that window near zero.

Filesystem isolation is not enough, because agents that test in a browser hit the second singleton. Chrome encrypts its cookies against the profile path and locks the profile directory, so two agents sharing one profile fight over session locks and debug ports.

We solve this with a fixed port-and-profile map, one slot per harness. The defaults look like this:

| Port | Agent | Profile |

| :--- | :--- | :--- |

| 9223 | Claude Code | agent-2-profile |

| 9224 | Cursor | agent-gamma |

| 9225 | Antigravity | agent-delta |

| 9226 | Copilot | agent-copilot |

To run several instances of the same harness, each needs its own slot too. We launch extra Claude browsers as c2, c3, c4, which map to ports 9240, 9241, 9242 with fresh profiles. A self-healing wrapper, scripts/chrome-mcp-launch.sh , checks whether that agent's port is already up, launches Chrome on the right port and profile if not, waits for the debug endpoint to answer, then binds the automation server to it. Because each agent's config calls the wrapper with its own name, editing one harness's setup never touches another's.

Here is a non-obvious bug that cost us real debugging time. Claude Code's background daemon pools a single automation-server instance across every background session, keyed by the command and its arguments. Since every session shares the identical browser-launch command, a backgrounded session silently reuses the daemon's first browser connection on port 9223 — the per-session port variable never reaches the pooled process.

The fix is to run slot sessions in the foreground. A foreground process spawns its own automation server, which inherits its own environment and therefore its own port. This is the kind of failure you only find by reading process trees, and it is a good reminder that "isolated" config is not isolated if a daemon dedupes it upstream.

The third singleton is source files that concentrate shared state. Our worst offender is components/admin/studio/PromptEditorPanel.tsx — about 10,000 lines holding four tab UIs against one state block. Worktrees do not save you here, because the conflict is semantic: two agents making reasonable edits to the same dense file produce a merge that reverts one of them.

The rule we wrote into our project instructions is blunt: only one agent may edit that file at a time. The thin wrapper files that import it are safe to parallelize; the monolith is not. When you run a fleet, audit your repo for these hotspots and name them explicitly. A one-line rule in your agent instructions ("never run parallel agents on file X") prevents a class of silent reversions that no amount of worktree isolation will.

With agents isolated, you still want to see what the fleet is doing. We register every agent on startup into a shared control plane — a single mutation that records the agent's ID, type, shell PID, and working directory. A monitoring page then shows active sessions at a glance, so before assigning new work you can see who is already editing what.

This registry is also where the "is anyone in the monolith right now?" question gets answered in practice. Cheap coordination state beats expensive merge-conflict archaeology every time.

Not every agent should run the same model. Our division of labor: use the strongest reasoning model for judgment, planning, and any change where wrong wiring is expensive to undo, and a faster model for mechanical implementation once the plan is set. A planning agent decomposes a feature and hands well-scoped, unambiguous units to implementation agents. The expensive model is the bottleneck you protect; the cheap model is the throughput you scale.

If you adopt one thing from this guide, adopt the lifecycle. Every agent, every session, follows the same loop:

# 1. Sync from the remote before touching anything
git fetch origin && git rebase origin/main

# 2. ... do the work in an isolated worktree ...

# 3. Commit, then immediately merge back and push
./.claude/scripts/merge-to-main.sh

Wrap that around per-agent browser isolation and a hands-off rule for your hotspot files, and a ten-agent fleet stops fighting itself. The hard-won lesson is that parallel AI agents do not fail loudly — they fail by quietly erasing work. The protocol is not bureaucracy; it is the lock you do not otherwise have.