How to run several AI coding agents at once without wrecking your repo

Running one AI coding agent is straightforward. Running three is where people get hurt — and almost never for interesting reasons. The failures are mundane: two agents editing the same file, a dev server that can't bind to port 3000 twice, and a pile of diffs nobody actually read.

Tooling is moving this way regardless. Cursor's Projects beta puts a coordinator agent in charge of delegating to subagents, and Claude Code ships subagents that each run in their own context window. So it's worth learning the workflow properly rather than discovering the failure modes one at a time.

Here's the order that works.

1. Split by boundary, not by line count

The single highest-leverage decision is how you cut the work, and you make it before any agent starts.

Good splits follow feature or domain boundaries — parts of the codebase that barely touch each other:

• Agent A: add rate limiting to the API layer
• Agent B: write the onboarding email templates
• Agent C: migrate the test suite from Jest to Vitest

Bad splits sound efficient and aren't: "you do the first half of the refactor, you do the second half." Parallel agents touching the same files guarantee integration problems — the Upsun write-up makes the same point, quoting the GitButler team.

A simple test: if you'd hesitate to give these two tasks to two humans who can't talk to each other, don't give them to two agents.

2. Give every agent its own directory

The most common architectural mistake is pointing several agents at one working directory. They overwrite each other's files, interrupt each other's branch checkouts, and corrupt lock files.

git worktree fixes this. A worktree is a second working directory linked to the same repository — separate HEAD and index, shared history and objects, so you're not cloning the repo five times. The Git documentation puts it plainly: "A git repository can support multiple working trees, allowing you to check out more than one branch at a time."

git worktree add -b feature-auth   ../wt-auth   main
git worktree add -b emails-rewrite ../wt-emails main
git worktree add -b vitest-migrate ../wt-vitest main

git worktree list        # see them all

Then start one agent inside each directory, each with a narrow prompt. When a branch is merged and you're done:

git worktree remove ../wt-auth
git worktree prune       # clean up stale admin files

Two restrictions worth knowing up front. add refuses to check out a branch that is already checked out in another worktree — that's a feature, not an obstacle, so give each agent its own branch. And remove refuses to delete a worktree with uncommitted changes unless you force it, which quietly saves you from throwing away an agent's unfinished work.

3. Budget for the environment, not just the code

Isolated directories don't isolate everything else. The pitfalls Upsun documents are worth pre-empting:

• Ports. Three agents all starting a dev server on 3000 means two failures. Assign each worktree a port range up front and put it in that worktree's env file.
• Databases and Docker. Worktrees share your local database, Docker daemon and caches. Two agents running migrations against one database is a race condition. Give each a separate schema or database name.
• Disk. Every worktree needs its own npm install. One user reported a 2 GB codebase ballooning to 9.82 GB in 20 minutes of automatic worktree creation. Prune aggressively.

4. Use subagents to protect your context window

Separate directories solve file collisions. They don't solve the other scaling problem: your main conversation filling up with search output and test logs.

Claude Code's subagents address that. Each runs in its own isolated context window with its own system prompt and tool access — it doesn't see your conversation history or the files you've already read, and only its summary comes back. Verbose exploration stays out of your main context.

You define one as a markdown file in .claude/agents/ (project) or ~/.claude/agents/ (all projects):

---
name: test-writer
description: Writes and runs unit tests for a single module
tools: Read, Glob, Grep, Edit, Bash
model: sonnet
---

You write focused unit tests. Run the suite before reporting back.
Never modify source files outside the module you were given.

Two fields matter for parallel work. isolation: worktree runs the subagent in its own git worktree automatically. background: true keeps it running concurrently while you keep working. The default concurrent limit is 20 subagents — worth knowing, though if you're anywhere near it, your bottleneck is review, not compute.

The tools field is a real safety mechanism, not decoration. A subagent given only Read, Glob, Grep cannot write to your repo no matter how confidently it decides it should.

5. Make review the bottleneck on purpose

Three agents produce three diffs. Merging them all because they look plausible is how parallelism turns into a bad afternoon.

Review each branch separately, on its own, before merging anything:

git diff main..feature-auth

Then merge one branch, re-run the full test suite, and only then merge the next. Integrating all three at once means a broken suite tells you nothing about which agent caused it.

Notably, even Cursor's coordinator is blocked from pushing to main branches on its own. If the vendors building this don't trust the fleet unsupervised, your setup shouldn't either.

The honest summary

Parallel agents are a throughput multiplier on a step that probably wasn't your bottleneck. Typing code faster doesn't help if you can't review it faster.

Start with two agents on genuinely independent tasks. Get the worktree, port and review habits solid. Add a third only once the first two stop generating cleanup work — because an agent whose output you merge unread isn't saving you time, it's borrowing it at interest.