If you have ever opened a second Claude Code session on the same repository and come back to a stashed, half-merged mess, the fix is not a better prompt. It is a separate checkout per session. Anthropic ships a --worktree flag for exactly that (official docs), and every major competitor shipped the same idea in the first half of 2026. We run this setup daily across our own multi-locale publishing codebase. Here is the sequence that works, the environment problem nobody warns you about, and the ceiling you hit that no tool removes.
What actually collides when you run agents in parallel
Three separate collisions get lumped together as "the agents fight each other," and they have different fixes.
File edits. Two sessions editing the same file on the same checkout produce the merge conflict that takes longer to untangle than the original task (Developers Digest). A branch switch in one terminal silently changes the files under a running session in another.
Environment. A second checkout has no .env, no installed dependencies, and frequently the same hardcoded port as the first one. The agent then debugs your setup instead of your ticket.
Attention. Ten agents produce ten diffs. That is the collision no flag fixes, and it is the one that decides how many agents you should actually run.
Step 1: Give every session its own worktree
A git worktree is a separate working directory with its own files and branch, sharing the same history and remote as your main checkout. Claude Code creates one for you and starts the session inside it:
claude --worktree feature-auth
By default this creates the worktree under .claude/worktrees/feature-auth/ at your repository root, on a new branch named worktree-feature-auth. Run the same command with a different name in another terminal for a second isolated session. Omit the name and a generated one such as bright-running-fox is used (official docs).
Keep the worktree directory out of your main checkout's status:
echo ".claude/worktrees/" >> .gitignore
Interactive runs require workspace trust. If you have never run Claude Code in that directory, run it once bare to accept the trust dialog, or the flag exits with an error. Non-interactive runs with -p skip the trust check entirely.
To branch from a pull request instead of your default branch, pass the number prefixed with #, quoted so your shell does not read it as a comment:
claude --worktree "#1234"
Expected result: git worktree list shows one entry per running session, each on its own worktree-* branch, and no session can see another's edits.
Step 2: Copy the environment the worktree does not inherit
This is the step that fails first, and it fails quietly. A worktree is a fresh checkout, so gitignored files never come along.
❌ Before. You start claude --worktree feature-auth, the agent runs the test suite, and it fails on missing environment variables. The agent then spends its context window diagnosing your local setup instead of the task.
✅ After. Add a .worktreeinclude file at your project root. It uses .gitignore syntax, and only files that match a pattern and are gitignored get copied, so tracked files are never duplicated:
.env
.env.local
config/secrets.json
The same claude --worktree feature-auth command now starts with a working environment, and this applies to every worktree Claude Code creates (official docs). Dependencies still need installing in the new checkout: either make that the agent's first instruction or run your project's setup script there yourself.
One default is worth changing. New worktrees branch from your repository's default branch on the remote, which is usually correct. When you fan agents out across work that only exists locally, branch from your current HEAD instead:
{
"worktree": {
"baseRef": "head"
}
}
Failure mode to watch: left at the default, a worktree started from an unpushed feature branch silently begins from main, and the agent appears to "lose" work that was never missing.
Step 3: Choose the coordination mode that matches the work
Isolation is not orchestration. Anthropic documents four distinct ways for Claude Code to parallelize, and picking the wrong one is a common and expensive mistake (official docs):
| Mode | What it gives you | Use when |
|---|---|---|
| Delegated workers | Side tasks run in their own context inside one session and return a summary | A search or log dump would flood your main conversation |
Agent view (claude agents) | One screen to dispatch and monitor background sessions | You have independent tasks and want to check back later |
| Agent teams | Coordinated sessions with a shared task list and direct messaging, managed by a lead | You want the work split, assigned, and kept in sync for you |
| Dynamic workflows | A script that runs many workers and cross-checks their results | A codebase-wide audit or a several-hundred-file migration |
That last point is the trap. Agent view moves each dispatched session into its own worktree automatically. Agent teams do not. Turn teams on, skip the file-ownership split, and you have reintroduced exactly the collision Step 1 removed.
Once several sessions run unattended, you need somewhere to watch their state land — the same argument we made for an agent control plane.
For custom agent definitions in .claude/agents/, make the isolation permanent with one frontmatter line:
---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---
Apply the requested refactor across every affected file, then run the tests
and report the results.
Step 4: Sandbox the sessions you stop watching
Worktrees isolate files inside your repository. They isolate nothing else on your machine, and Claude Code does not pretend otherwise. That matters as soon as agents run with permission prompts turned off.
Docker Sandboxes give each agent a disposable environment:
sbx run claude ~/my-project
The default startup command inside a sandbox is claude --dangerously-skip-permissions, which is defensible precisely because the blast radius is a container rather than your laptop (Docker docs). Clone mode goes further: the agent works in a private git clone inside the sandbox while your host repository is mounted read-only.
sbx run --clone claude
Two documented constraints will bite you (Docker sandbox usage):
- Clone mode is fixed at creation time. Switching an existing sandbox means removing and recreating it.
- Clone mode is rejected from inside any worktree other than the main one, because the read-only bind mount cannot resolve the worktree's
.gitpointer file. Run it from your main checkout.
Sandboxes also do not inherit user-level configuration from ~/.claude; only project-level configuration in the working directory is visible inside. Agents that depend on your personal settings behave differently there, and discovering that mid-task is worse than knowing it up front.
Step 5: Set the concurrency cap from your review capacity
Every vendor now ships the same isolation primitive. Cursor 3.0 retired Composer for an Agents Window that runs agents across isolated worktrees and SSH remotes (Level Up Coding). The GitHub Copilot desktop app, announced at Microsoft Build on June 2, 2026, gives each parallel session its own worktree (Digital Applied), and GitHub moved parallel sessions to general availability in VS Code on July 9, 2026 (TechTimes). Desktop orchestrators converged on the identical model: one agent per worktree, with a diff to approve (Parallel Code). Practitioner tutorials now frame sequential sessions as a tool constraint rather than a task constraint (worktrees explained).
When every tool solves isolation the same way, isolation stops being the differentiator. What is left is your throughput as a reviewer.
We cap ourselves at four concurrent sessions on one repository, because past that point the time we spend reviewing and merging their output costs more than the parallelism saves. The tenth agent is not blocked by git. It is blocked by the fact that ten diffs arriving together get reviewed worse than three diffs arriving in sequence, and a badly reviewed agent diff is more expensive than a task you never started.
That is the same cost logic we applied to per-token model billing: the headline unit price is rarely the number that decides the bill.
It is also why we keep arguing for choosing a minimal agent over a maximal one when the task does not need the bigger tool.
A practical way to find your own number: run three agents for a week and measure how long each diff waits before a human opens it. If that wait grows, adding agents is adding queue, not capacity. Running several sessions at once also multiplies token usage, so the cost curve moves before the value curve does.
Set the cap deliberately, isolate properly below it, and parallel agents become a real multiplier. Treat the agent count as the goal and you have built a queue with extra steps. If you want the ground-level version first, start with our honest on-ramp for non-engineers; if you want this designed around your codebase rather than a demo, our engineering team does exactly that work.
Frequently Asked Questions
Do I need worktrees if I only run two agents? Yes, if both edit files. Two Claude Code sessions on one checkout collide on branch switches and stashes regardless of count (Developers Digest). The setup cost is a single flag, so there is no threshold worth waiting for.
What happens to worktrees when a session ends?
On exit Claude Code checks for changed files, untracked files, and new commits. Clean unnamed sessions are removed automatically; anything holding work prompts you to keep or remove it. Non-interactive -p runs never clean up, so remove those with git worktree remove (official docs).
Are agent teams a replacement for worktrees? No. Teams coordinate work, worktrees isolate files. Teams are experimental, disabled by default, and explicitly do not isolate teammates in worktrees, so file ownership must be partitioned manually (official docs).
Is a sandbox necessary, or is a worktree enough? A worktree isolates repository files only. If agents run with permission prompts disabled, use a sandbox so the blast radius is a container (Docker docs). For supervised sessions on a trusted repository, a worktree alone is reasonable.
How many parallel agents is too many? The limit is review throughput, not tooling. If diffs wait longer before a human opens them each week, you are past your cap. We use four on a single repository and measure the wait rather than the agent count.
Sources
- Run parallel sessions with worktrees — Claude Code docs — Anthropic, updated 2026-07-17
- Run agents in parallel — Anthropic, updated 2026-07-18
- Claude Code in Docker Sandboxes — Docker, updated 2026-07-15
- Docker Sandboxes usage and clone mode — Docker, updated 2026-07-15
- GitHub closes the agentic loop in VS Code — TechTimes, 2026-07-09
- Parallel Code vs Conductor — Parallel Code, 2026-06-15
- Git worktrees explained for parallel AI agents — bri, 2026-06-14
- The 2026 playbook for running parallel agents — Developers Digest, 2026-06-10
- GitHub Copilot app: agent-native desktop orchestration — Digital Applied, 2026-06-06
- AI Daily Digest, May 22, 2026 — Level Up Coding, 2026-05-22