TL;DR
Running two or three coding agents in one repo only works if you isolate them at the filesystem level. The 2026 recipe: one git worktree per agent (so they physically can’t touch the same files), one shared AGENTS.md at the repo root for conventions, one written role per agent, and merge through PRs in a human-controlled order. Skip any of those and you get merge conflicts, port collisions (EADDRINUSE), or silent overwrites within the hour.
The four problems you actually have to solve
Multiple agents in one project sounds powerful, and it is — but only after you’ve solved four concrete problems:
- Workspace ownership — who is allowed to edit which files, right now.
- Shared conventions — one source of truth for naming, lint, and do-not-touch paths.
- Branch and merge discipline — agents must never push to the same branch or to
main. - Runtime isolation — separate ports and databases so parallel dev servers don’t deadlock.
This is the playbook for handling all four. It assumes you’re already comfortable with one agent and want to farm work out in parallel: scaffolding in Codex, refactoring in Claude Code, inline edits in Cursor. It’s equally useful for a two-person team where each developer drives a different agent.
Practical ceiling first: most teams find 2 to 4 parallel agents manageable. Past that, the time you spend decomposing tasks, reviewing output, and resolving merges eats the parallelism gain.
Step 1 — Isolate with git worktrees, not branches
A git worktree checks out a branch into its own directory from the same repository, so each agent gets a private filesystem. Two agents literally cannot lock or overwrite the same file mid-edit.
# from the main checkout
git worktree add ../proj-refactor refactor/auth
git worktree add ../proj-scaffold scaffold/billing
git worktree add ../proj-inline feature/checkout-ui
git worktree list # confirm the three new dirsWhy not just switch branches in one checkout? Because a single shared working tree is exactly how you end up with mystery uncommitted changes and half-applied diffs that no agent will admit to.
Note that each worktree needs its own dependencies. node_modules is not shared, so run npm ci --prefer-offline (or your package manager’s equivalent) once per worktree. If one agent bumps a dependency, reinstall in the others before merging or you’ll hit a package-lock.json conflict.
Step 2 — One AGENTS.md at the root, bridged into Claude Code
In 2026 the convention has settled, but the naming did not fully converge, so get this detail right:
AGENTS.mdis the open standard (now maintained under the Linux Foundation, 60,000+ repos). Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, and Zed read it natively.- Claude Code reads
CLAUDE.md, notAGENTS.md— confirmed in Anthropic’s docs as of mid-2026. If a repo only hasAGENTS.md, Claude Code loads zero project instructions and says nothing.
So make AGENTS.md the single source of truth, then bridge it into Claude Code. The cleanest bridge is a one-line import in CLAUDE.md:
<!-- CLAUDE.md -->
@AGENTS.md
# Claude-specific notes go below the importClaude Code expands @AGENTS.md at session start. (A ln -s AGENTS.md CLAUDE.md symlink also works on macOS/Linux, but the import is friendlier on Windows and lets you add Claude-only rules.) This is the reverse of the old advice that put CLAUDE.md first — AGENTS.md is the standard everything else already speaks.
Why it matters: in agentic-coding evaluations, agents with no project-context file completed tasks correctly around 30% of the time; with a solid context file in place, that jumped to roughly 90%. A shared AGENTS.md is the cheapest reliability upgrade you can ship.
A minimal AGENTS.md that all three agents obey:
# AGENTS.md
## Build & test
- Install: npm ci
- Lint (must pass before commit): pnpm lint
- Test: pnpm test
## Conventions
- Conventional Commits required
- Named exports only; no default exports
## Do not touch
- infra/ migrations/ .env* secrets/
## Workflow
- Open a PR. Never merge your own PR. Never push to main.Step 3 — Assign one written role per agent
Drift in roles is where chaos starts. Write the split down and don’t let an agent freelance into another’s lane. Based on each tool’s strengths as of June 2026:
| Agent | Best at | Use it for | Avoid |
|---|---|---|---|
| Claude Code (Opus 4.7 / Sonnet 4.6, 1M context) | “Read 30 files, edit 8” | Large refactors, codebase-wide renames, architecture changes | Tiny one-line tweaks |
| Cursor agent (Sonnet 4.6 / GPT-5.5 / Composer 2.5) | “I’m here, fix this” | Inline edits, small bug fixes, UI tweaks | Sprawling multi-file refactors |
| Codex (GPT-5.5) | “Go generate the new thing” | Scaffolds, migrations, boilerplate, dependency bumps | Subtle cross-cutting logic |
| Aider | ”What could break this” | Test writing, edge-case enumeration | Greenfield architecture |
On benchmarks that justify the Claude-Code-for-refactors default: Opus 4.7 leads SWE-bench Verified at 87.6% (vs Gemini 3.1 Pro 80.6%) and SWE-bench Pro at 64.3% (vs GPT-5.5 58.6%). GPT-5.5 leads Terminal-Bench 2.0 at 82.7%, which is part of why Codex is strong at command-driven scaffolding. Don’t make one agent do all four jobs unless your project is genuinely small.
Step 4 — Isolate runtime: ports and databases
This is the step most guides skip, and it’s the one that produces the ugliest failures. If three agents each run npm run dev on the default port, the second and third die with EADDRINUSE, and background test runs can deadlock or corrupt a shared local database.
Give each worktree its own port and database. Don’t symlink .env — copy it, then add a .env.local override per worktree:
# in ~/proj-scaffold/.env.local
PORT=3002
DATABASE_URL=postgres://localhost:5433/app_scaffoldA simple convention: app ports 3000–3009, database ports 5432–5441, one offset per worktree. Bake it into a setup script so every new agent gets the next free port automatically.
A concrete 3-agent setup
~/proj/main # main worktree, human only
~/proj/refactor # Claude Code, branch: refactor/auth, PORT=3001
~/proj/scaffold # Codex, branch: scaffold/billing, PORT=3002
~/proj/inline # Cursor, branch: feature/checkout-ui, PORT=3003Each worktree carries the same AGENTS.md (plus a CLAUDE.md that imports it). The human reviews and merges; agents never git push to main. Cursor 3.2 (shipped April 24, 2026) automates the worktree side of this from its Agents Window — when you move an agent into a worktree it creates the isolated checkout for you, and a one-click button promotes a finished worktree to the foreground for review.
Step 5 — Coordinate through PRs, lock shared files
- One PR per agent. Each agent opens its own PR; you merge in the order that makes sense. Never have two agents pushing to the same branch — that guarantees a force-push or lost commits.
- Lock turn-taking on shared files. If
config/app.tsis being edited in the Cursor worktree, no other agent touches it until that PR merges. This is a written rule, not a vibe. - Resolve cross-agent conflicts yourself. Don’t ask an agent to resolve a merge conflict in code it didn’t author — it lacks the context and will guess.
- Run one human-reviewed combined test pass before merging into
main. Each agent’s CI can be green individually while the combined diff breaks.
Recommended end-to-end flow
assign roles → one worktree per agent → shared AGENTS.md (+ CLAUDE.md import) → isolate ports/DB → one agent per file at a time → each agent opens a PR → human merges in order → final combined test pass.
Expect it to feel slower in week one and roughly 2x faster by week three, once the worktree-and-PR rhythm is muscle memory.
Common mistakes
- Two agents in one workspace — merge hell within an hour.
- No shared conventions doc — each agent invents its own naming, lint, and import style.
- Only an
AGENTS.md, noCLAUDE.mdbridge — Claude Code silently runs with zero project context. - Letting agents merge their own PRs — bypasses the only human checkpoint you have.
- Same branch, multiple agents — guaranteed force-push or lost commits.
- Shared ports/DB —
EADDRINUSEcrashes and corrupted test runs. - Skipping the final combined test pass — per-agent green CI doesn’t mean the merged diff works.
FAQ
Can two agents safely edit the same file at the same time? No. Even with separate worktrees, concurrent edits to one file produce merge conflicts that are painful to resolve by hand. Lock the file to one agent until its PR merges.
Do I really need worktrees, or are branches enough? Worktrees are dramatically less error-prone. Sharing a single checkout between agents is the classic source of mystery uncommitted changes. Cursor 3.2 and Claude Code both support worktrees directly as of 2026.
My repo has AGENTS.md but my teammate uses Claude Code — what do I do?
Add a one-line CLAUDE.md containing @AGENTS.md (or symlink CLAUDE.md to AGENTS.md). Claude Code does not read AGENTS.md natively, so without this bridge it gets no project instructions.
Which agent should review the others’ PRs?
You can use a dedicated “review agent” role (often Claude Code with a /review command) to do a first pass, but always require human sign-off before merge.
What’s the practical limit on parallel agents? 2 to 4 for most teams. Cursor can technically run up to 8 agents on one problem and auto-pick the best result, but coordination and review overhead climbs fast beyond a handful.
Is this worth it for a solo developer? If your project is under ~20k lines, usually not — the coordination overhead beats the parallelism. It pays off on larger codebases where work genuinely splits along feature or domain boundaries.
Related
Tags: #AI coding #Tutorial