Running Coding Agents in Parallel with Git Worktrees

TL;DR: if you run Claude Code, Codex, or similar agents, a single shared checkout is a disaster when you spin up multiple agents in parallel. git worktree gives you separate working directories, each on its own branch, sharing the same repository: zero conflicts, zero unnecessary push/pull, direct merge into integration.

The problem: agents stepping on each other

Two agents on the same repo, same folder, same branch:

• editing the same files
• overwriting each other's changes
• no context isolation

Result: chaos, even if each agent works perfectly in isolation.

The fix: one worktree per agent

git worktree add ../feature-login -b feature/login main
git worktree add ../feature-payments -b feature/payments main
git worktree add ../integration -b integration main

Resulting structure:

project/
├── main/               → branch main
├── integration/        → branch integration
├── feature-login/      → branch feature/login
└── feature-payments/   → branch feature/payments

Each agent gets:

• its own folder
• its own branch
• the same shared repository

No file conflicts, no working directory conflicts.

The surprising detail: no push, no pull

All worktrees belong to the same local repository. So integration can directly:

cd ../integration
git merge feature/login
git merge feature/payments
npm test

Git already knows all local branches. Push and pull only matter when humans enter the loop:

• PRs, review, CI, audit trail
• Local agent plane → remote human plane

Proper cleanup

git worktree remove ../feature-login
git branch -d feature/login

git worktree remove deletes the folder and cleans Git's internal registry. If you already nuked the folder by hand, git worktree prune fixes the bookkeeping.

Full cycle for one task:

git worktree add ../feature-login -b feature/login main
cd ../feature-login && git add . && git commit -m "feat: login"
cd ../integration && git merge feature/login && npm test
git worktree remove ../feature-login
git branch -d feature/login

Shared runtime: the port problem

Worktrees isolate files and branches, not processes. Two agents running npm run dev or test suites will fight over :3000, local test databases, and RAM for headless browsers.

Simple workaround: each worktree gets its own .env.local with a dedicated port:

echo "PORT=3101" > ../feature-login/.env.local
echo "PORT=3102" > ../feature-payments/.env.local

For shared test databases, concurrent E2E suites, and real isolation, you need a further step — perhaps containers or worktrees on separate machines.

Critical note: stash is shared

⚠️ refs/stash is unique in the shared repo. If one agent stashes in a worktree, the other worktree sees it and can apply it in the wrong place.

Rule: never use stash with parallel agents. Use only commits on your own branch.

What the ecosystem says in 2026

This pattern is no longer a niche trick. Multiple production teams and tools have validated it.

Worktree-per-task vs worktree-per-agent
Practitioners recommend worktree-per-task as the default: each task gets its own branch and worktree, and agents are assigned to worktrees rather than owning them permanently. This keeps reuse simple and avoids stale state.

Native tool support

• Claude Code supports --worktree / -w to spawn an isolated session, plus subagent isolation inside separate worktrees.
• Codex CLI does not have a native --worktree flag; the common pattern is manual git worktree add plus codex --cd ../path.
• Cursor added first-class worktree support in the 2026.1 release.

Orchestration layers
Tools like Intent, AQ, Atlas, Nimbalyst, and Warp’s cloud orchestration automate worktree creation, assignment, review, and cleanup. They treat a worktree as the unit of isolation and build scheduling, diff review, and merge gating on top of it.

Conflict prediction
Tools like Clash predict merge conflicts before they happen by monitoring which files parallel worktrees are touching.

Five failure modes to design around

1. Port and service collisions — agents fight over the same dev server, database, or cache. Fix: explicit .env.local per worktree.
2. Shared external state — databases, Docker volumes, and queues are still shared. Fix: separate databases or containers per worktree.
3. Loose task boundaries — two agents touch the same module and produce a conflict neither anticipated. Fix: explicit file ownership before launching.
4. Uncommitted state is invisible — one agent’s in-progress edits are not seen by another until committed. Fix: WIP commits for handoffs.
5. Review becomes the bottleneck — worktrees make it cheap to start many agents, but reading many diffs is still expensive. Fix: narrow task scope, sequential merge, and one combined test pass.

A practical workflow

1. Map boundaries first. Decide which files each agent can touch.
2. Create one worktree per task. Branch from a clean base; avoid forcing the same branch twice.
3. Bootstrap each worktree. Install dependencies, copy env files, assign ports.
4. Run agents with scoped prompts. Tell each agent its ownership boundary and success criteria.
5. Merge sequentially. One branch at a time, with tests between merges.
6. Clean up. git worktree remove and delete the branch when the feature is merged.

Where this fits in enterprise delivery

This is not just a solo-developer productivity trick. In enterprise settings, worktree isolation maps cleanly onto:

• Requirement-to-Deploy value streams: each worktree is a controlled change in progress, ready for approval workflow.
• Change control: commits are auditable, revertible, and tied to specific task branches.
• Integration gating: the integration worktree becomes the single merge point with mandatory testing.
• Cost governance: parallel execution reduces wall-clock time, but only when task boundaries are tight enough to avoid rework.

The pattern has become so standard that 2026 guides from Augment Code, MindStudio, Warp, and multiple independent practitioners describe it as the default baseline for multi-agent coding — not an advanced technique.

Link

📄 Original article: https://dev.to/servatj/running-coding-agents-in-parallel-with-git-worktrees-507i