Run Agents in Parallel

Running one agent at a time is the obvious starting point. Running several at once is where the real productivity multiplier lives. This guide shows the concrete mechanics: how to isolate agents from each other with git worktreesa git feature that lets one repository have multiple checked-out branches simultaneously, each in its own directory, how to divide work so agents don't collide, and where the strategy breaks down.

Why use worktrees instead of branches?

If you start two Claude Code sessions in the same working directory, they share the index, HEAD, and every file. One agent's mid-flight edits corrupt the other's context. A git stash mid-task is worse.

Worktrees give each agent a fully independent checkout of the repo, linked to the same .git object store. They share history and objects but nothing in the working tree. Each agent sees only its own files, its own staged changes, and its own branch tip.

# Primary repo is already checked out at ~/projects/myapp
git worktree add ../myapp-feat-auth   -b feat/auth
git worktree add ../myapp-feat-search -b feat/search
git worktree add ../myapp-bugfix-429  -b bugfix/rate-limit

You now have three directories alongside your main checkout. Each is a full working tree. Each maps to exactly one branch. Git will refuse to check out the same branch in two worktrees, which is the guard you want.

git worktree list
# /Users/you/projects/myapp            abc1234 [main]
# /Users/you/projects/myapp-feat-auth  000000  [feat/auth]
# /Users/you/projects/myapp-feat-search 000000 [feat/search]
# /Users/you/projects/myapp-bugfix-429  000000 [bugfix/rate-limit]

How do I start parallel Claude Code sessions?

Open a terminal tab per worktree. In each tab, navigate to that worktree's directory and start Claude Code:

# Tab 1
cd ../myapp-feat-auth
claude
 
# Tab 2
cd ../myapp-feat-search
claude
 
# Tab 3
cd ../myapp-bugfix-429
claude

Each session has its own conversation context, its own tool calls, and its own view of the filesystem. They cannot see each other's changes until you explicitly merge or cherry-pick.Common gotchaA fresh worktree only checks out tracked files, so your gitignored node_modules, .env, and build caches are missing, and every agent fails on its first command.Run your install and env-copy step in each new worktree before you start the agent, or symlink node_modules from the main checkout so all the trees share one install.

If you prefer a single terminal, use a multiplexer like tmux or the split-pane feature in your terminal app. Claude Code has no native multi-session UI, but the Anthropic web interface added parallel task support in late 2025 for users who prefer a browser workflow.

How do I divide work so agents don't collide?

Parallelism only helps when the tasks do not overlap. The clearest signal: if agents A and B would both need to edit the same file, they are not independent.

Good candidates for parallel agents:

Bad candidates:

Write your task list before you spin up agents. If you cannot draw a clear file-boundary between two tasks, collapse them into one agent.

The constraint in that prompt ("do not touch any other files") is load-bearing. Agents will expand scope if you let them.

The fan-out / integrate loop

You are the integrator. The agents fan out and work independently, then you review each branch and merge in a controlled order. This is where the bottleneck moves: from writing code to reading and reviewing diffs.

What order should I merge the branches in?

Merge the branch most likely to cause conflicts first. Others can then rebase on top of the updated main before you review them.

# Merge the bugfix first (smallest, most contained)
git switch main
git merge --no-ff bugfix/rate-limit
 
# Rebase feat/auth onto updated main before reviewing
cd ../myapp-feat-auth
git fetch origin
git rebase main
 
# Then review and merge feat/auth
cd ../myapp
git merge --no-ff feat/auth
 
# Finally rebase and merge feat/search
cd ../myapp-feat-search
git rebase main
cd ../myapp
git merge --no-ff feat/search

If a rebase surfaces a conflict, you have two choices: resolve it yourself, or drop the conflicted branch back to an agent with explicit context about what changed on main.

Pasting the relevant diff or interface into the prompt is faster than asking the agent to re-read the whole repo.

Cleaning up worktrees

When a branch is merged, remove its worktree:

git worktree remove ../myapp-feat-auth
git worktree remove ../myapp-feat-search
git worktree remove ../myapp-bugfix-429
 
# If a worktree directory was deleted manually, prune the stale refs
git worktree prune

Git will refuse to remove a worktree with uncommitted changes unless you pass --force. Treat that refusal as a safety net, not an annoyance.

Monitoring multiple sessions

You are now context-switching between tabs instead of writing code. A few habits that keep this manageable:

• Name your tabs after the branch, not the directory. "feat/auth" is faster to find than "myapp-feat-auth."
• Check in at natural breakpoints. Let an agent run to a logical stopping point (tests pass, a subtask is complete) before switching attention to it. Interrupting mid-task and re-prompting wastes context.
• Set a clear done condition in the initial prompt. "Run tests and tell me the result" gives you a terminal state to check for, rather than needing to read a scrollback of tool calls to know if it finished.
• Keep a scratchpad (a plain text file, a note, anything) listing what each agent is working on and what you expect it to produce. Three agents running simultaneously is easy to track. Seven is not.

Context fragmentation

Each agent session has its own context window. None of them know what the others are doing. This is by design for isolation, but it creates drift:

• Agent 2 might invent a helper function that Agent 1 already implemented.
• Agent 3 might choose a different error-handling pattern than Agents 1 and 2.
• Without a shared style prompt, each agent defaults to its own conventions.

Mitigations:

1. Give all agents the same system-level context at the start of each session. A short block describing naming conventions, error handling patterns, and test style is worth copying into every prompt.
2. Reference existing files explicitly. "Match the pattern in src/api/users.ts" is more reliable than "follow the project conventions."
3. Review for consistency during integration. Parallel agents produce parallel code. Homogenising style is a human job.

When should I not run agents in parallel?

Parallel agents add coordination overhead. The overhead only pays off when tasks are large enough that the parallel speedup exceeds the time you spend on setup, monitoring, and integration.

Do not parallelise when:

• The total task would take one agent less than 15 minutes. Setup cost exceeds the gain.
• You do not understand the codebase well enough to draw clean file boundaries. You will produce merge conflicts and confusing code.
• The tasks are sequential by nature (B depends on A's output). Running them in parallel means B either guesses A's interface or blocks waiting.
• You are near a deadline and cannot afford conflict resolution. One focused agent is lower risk.
• The codebase has a large shared config, a single entry point that everything imports, or a monolithic module. Boundaries are hard to find and conflicts are frequent.

Honest limits

git worktrees solve the filesystem isolation problem cleanly. They do not solve:

• Shared state in a running process. If your dev server reads from a database or a cache, concurrent agents might interfere through that layer even if their files don't overlap.
• Non-deterministic lockfiles. npm install in two worktrees at the same time can produce different lockfiles depending on registry timing.Common gotchaIf you symlinked one node_modules to share installs, two agents running npm install at once write to the same folder and leave it half-corrupted.Pin every worktree to a fixed dependency set before you start, and let only one agent add or upgrade packages at a time.
• Your own review bandwidth. Three agents in parallel means three PRs to review. The agents scale; you do not. Calibrate to the number of branches you can review in a session.
• Long-running agent errors. An agent that goes off-track in one worktree keeps consuming tokens and time while you are focused on another tab. Check in at intervals, not only at the end.

The mental model that works in practice: treat parallel agents as junior developers on separate tasks. You write the tickets, they execute, you review and integrate. The productivity gain is real and significant. The coordination cost is also real and is entirely yours to carry.

Quick reference

# Create worktrees
git worktree add <path> -b <branch>
 
# List all worktrees
git worktree list
 
# Remove a worktree (branch must be merged or you pass --force)
git worktree remove <path>
 
# Clean up stale entries after manual deletion
git worktree prune
 
# Start Claude Code in a worktree directory
cd <worktree-path> && claude

For the next step after parallel agents, the orchestrator-worker pattern covers chaining agent outputs so one agent's result becomes another's input.