FIELD NOTE 001 / PARALLEL AGENT OPERATIONS
How to Run Multiple Coding Agents in Parallel Without Collisions
Git worktrees stop file fights. They do not stop port collisions, shared databases, duplicate builds, integration races, or one agent deleting another agent's work.
Summarize this article
Open a prefilled request in your preferred assistant.
Worktrees solve the first collision, not the system
The first time I ran a pile of coding agents at once, opening more terminals was the easy part. The difficult part was knowing which session owned which files, which one had stopped for a question, and whether the test result on screen even belonged to the branch I thought it did.
A Git worktree is the right filesystem boundary. Each agent gets a real checkout and branch, while every branch still shares the repository's object database. But the application layer remains shared unless you deliberately separate it: port 3000 is still port 3000, the development database is still the development database, and a six-agent build storm can still turn a fast machine into a decorative heater.
The three-layer isolation model
One branch and worktree for every agent that edits. Read-only reviewers can stay on a clean base tree.
Assign or reuse ports, databases, cache namespaces, credentials, and long-lived processes explicitly.
Queue immutable commits, let one owner validate the combined snapshot, then release the lease.
Most parallel-agent tutorials stop after layer one. That prevents the most obvious corruption, but the expensive failures happen when separate worktrees interact with the same machine and then race toward the same main branch.
1. Give every editing agent a visible ownership boundary
Start each task from the same reviewed base commit, and name the branch after the outcome rather than the agent. The worktree is disposable; the commit history is the durable handoff.
git fetch origin
git worktree add ../repo-auth -b feat/add-auth origin/main
git worktree add ../repo-tests -b test/add-auth-coverage origin/main
git worktree listAn agent owns its worktree, branch, edits, and child processes. It does not reset, clean, move, merge, or delete another agent's working directory. If tasks must touch the same hot file, either sequence them or divide ownership at a boundary the code actually has; pretending the conflict does not exist just postpones it until merge time.
2. Treat local resources like shared production infrastructure
Before an agent starts a watcher, browser, container, compiler, or preview server, it should check whether a compatible process already exists. Reuse it when the branch does not matter; allocate a distinct resource when it does.
# Example worktree-local resource manifest
APP_PORT=3102
TEST_DATABASE=app_agent_02
CACHE_NAMESPACE=agent-02
PREVIEW_OWNER=feat/add-authThe exact mechanism can be an ignored environment file, a launcher script, or a small registry. The invariant matters more than the tooling: every mutable shared resource has an owner, and nobody guesses.
3. Parallelize implementation; serialize expensive truth
Cheap focused checks belong with the implementation agent. Repository-wide builds, browser suites, container images, installers, and final integration tests should run against one declared snapshot under a short-lived lease.
- Review the change, commit it, push it when the repository workflow expects that, and publish the immutable commit to a ready queue.
- One agent claims the integration lease and snapshots the ready queue.
- Merge every clean candidate into a temporary integration tree.
- Refresh the queue once immediately before broad validation and include clean new arrivals.
- Run affected focused checks and one appropriate broad suite on the final combined tree.
- Complete only the entries actually included, release the lease even after failure, and leave conflicting candidates queued.
The single refresh is important. Refreshing forever means the batch never stabilizes; ignoring every arrival wastes a validation run. Anything that arrives after broad validation starts becomes the next batch. Boring, deterministic, done.
The handoff is part of the system
A finished agent should leave evidence, not vibes. The minimum handoff is the worktree, branch, immutable commit if one exists, dirty files, checks that actually ran, blockers, owned processes stopped, and the next action.
This also makes interruptions recoverable. If an agent disappears halfway through a task, another agent can distinguish incomplete work from a ready candidate without reverse-engineering six terminals and a suspiciously warm laptop.
Parallel coding agent failure taxonomy
I turned the recurring failure modes into a versioned, machine-readable taxonomy so the workflow can be audited instead of remembered. These are operational categories, not claims that worktrees or parallel agents automatically cause each failure.
| Phase | Failure mode | Detection signal | Prevention control |
|---|---|---|---|
| implementation | Two agents edit the same working tree | Unexplained dirty files, overwritten edits, or diffs containing another task | Give every editing agent its own branch and Git worktree |
| validation | Multiple previews or test servers claim the same port | Address-in-use errors or one agent testing another agent's server | Reuse one known server or allocate a documented port per worktree |
| validation | Parallel tests mutate the same database or cache namespace | Nondeterministic tests, disappearing fixtures, or cross-task state | Use a per-worktree database, schema, tenant, or namespace |
| implementation | Agents share generated files, caches, credentials, or local state | Lockfile churn, stale build output, authentication drift, or cache-only failures | Document which state is shared, isolate mutable state, and never copy secrets into commits |
| validation | Several agents launch the same compiler, browser suite, or container build | CPU, memory, or I/O saturation with duplicate commands in the process tree | Run cheap focused checks in parallel and serialize expensive validation |
| integration | Two agents merge or validate different snapshots at the same time | A supposedly tested commit is not the commit being merged | Publish immutable ready commits and allow one short-lived integration lease |
| integration | Every new ready change restarts a broad validation run | The integration batch never reaches a stable testable snapshot | Refresh the queue once before broad validation; defer later arrivals to the next batch |
| integration | An agent stops without recording what changed or what remains | A dirty worktree or branch exists with no trustworthy status | Require a handoff containing branch, commit, dirty files, checks, blockers, and next action |
| cleanup | A completed agent leaves a watcher, browser, server, or child process running | Ports remain occupied or resource use continues after the task ends | Track process ownership and stop only processes started by the finishing agent |
| cleanup | One agent resets, cleans, moves, or deletes another agent's work | Missing branches, worktrees, uncommitted files, or unexplained history changes | Resolve exact targets first and make every agent clean up only its own worktree |
Many live agents make the terminal itself part of the benchmark
I built GridBash because scattered terminals made parallel work harder to observe. It keeps real PTY-backed Codex, Claude, Gemini, and other CLI sessions in one selectable grid, with optional worktree isolation and explicit prompt routing.
Large grids also exposed a less glamorous bottleneck: repeatedly rendering panes that did not change. In GridBash's release-mode microbenchmarks, caching completed 120×40 pane buffers reduced unchanged-pane render time from 273.6 to 75.3 microseconds per frame, a 3.6× improvement. An ASCII fast path reduced terminal history filtering from 26.1 to 14.4 microseconds, a 45% improvement. The numbers are implementation benchmarks, not a claim that adding more agents makes software 3.6× faster.
Common questions
Can multiple coding agents use the same Git repository?
Yes. They should share the repository's Git history while editing through separate worktrees and branches. Agents that only review can use a clean read-only checkout.
Do Git worktrees isolate ports and databases?
No. Worktrees isolate checked-out files. Network ports, databases, caches, containers, credentials, and background processes remain shared unless your workflow separates them.
Should every agent run the full test suite?
Usually not. Each agent should run the narrow checks that prove its change. Run the expensive broad suite once on the combined integration snapshot, unless the risk or repository policy specifically requires more.
How many coding agents should run at once?
As many as have independent ownership and enough machine capacity to remain observable. Ten agents pointed at one hot file are not ten times faster; they are a merge conflict with a management layer.
Use the operating system, not just the idea
This page explains the full safety model. The supporting resources go deeper on each separate intent: exact worktree commands, orchestration architecture, measured terminal bottlenecks, and a planner that generates the setup.
Methodology and sources
This field note is based on building and operating GridBash, running parallel coding agents across active repositories, and the coordination workflow used on this site. The failure taxonomy records observed classes of operational risk; it does not report incident frequency. Version 1.0.0, last reviewed 2026-07-17.
- Git worktree documentation — Git
- Run parallel sessions with worktrees — Claude Code documentation
- GridBash source and documentation — GitHub
- Optimize high-load runtime throughput and latency — GridBash engineering log
- Building a Windows PTY Grid for Coding Agents in Rust — GridBash engineering article