How to run multiple Claude Code sessions in parallel

Why one directory does not work

The naive approach is to open three terminals in the same repository and start three agents. It fails quickly and in a way that is hard to diagnose, because the failure looks like the model being stupid.

• Agent A reads src/api.ts and plans an edit. Agent B rewrites the file. Agent A applies its edit to a version that no longer exists.
• Both run the test suite simultaneously against a tree that is half A's change and half B's. Both see failures neither caused.
• One runs git checkout or git stash and silently discards the other's uncommitted work.
• You end up with a diff containing two interleaved half-features and no clean way to separate them.

Three ways to parallelise, and when each is right

Worktrees are not the only parallelism Claude Code offers, and picking the wrong one is why people conclude "parallel agents do not work".

A custom subagent gets permanent file isolation by adding one line to its frontmatter.

---
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.

The setup

The fast path: let Claude Code do it

# terminal 1
claude --worktree csv-export
# terminal 2
claude --worktree tax-rounding
# terminal 3
claude --worktree dep-bump

Each call creates .claude/worktrees/<name>/ at the repository root on a branch named worktree-<name>, then starts the session there. Omit the name and Claude generates one such as bright-running-fox. Two setup steps make this pleasant rather than annoying:

# 1. Keep worktree contents out of your main checkout's git status
echo ".claude/worktrees/" >> .gitignore

# 2. Carry your gitignored env files into every new worktree
cat > .worktreeinclude <<'EOF'
.env
.env.local
config/secrets.json
EOF

An interactive --worktree run requires workspace trust. If you have never run Claude in that directory, run plain claude once to accept the trust dialog first. Non-interactive runs with -p skip the trust check.

The manual path, when you need control

Use git directly when you want a specific existing branch, a specific base, or a directory outside the repository.

cd ~/code/myapp
git checkout main && git pull

git worktree add -b feat/csv-export   ../myapp-csv    origin/main
git worktree add -b fix/tax-rounding  ../myapp-tax    origin/main
git worktree add -b chore/dep-bump    ../myapp-deps   origin/main

for d in ../myapp-csv ../myapp-tax ../myapp-deps; do
  (cd "$d" && cp ../myapp/.env . 2>/dev/null; npm ci) &
done
wait

cd ../myapp-csv  && claude "Add CSV export to the reports page. Tests included."
cd ../myapp-tax  && claude "Fix the tax rounding bug in checkout/total.ts. Add a regression test."
cd ../myapp-deps && claude "Bump minor dependency versions. Run the suite. Do not touch majors."

Choosing the base branch

By default a Claude-created worktree branches from the repository's default branch on the remote, so it starts clean. When you want it to carry your unpushed work instead, set worktree.baseRef to "head".

{
  "worktree": {
    "baseRef": "head"
  }
}

How the isolation is actually enforced

This is the part that makes parallel sessions safe rather than merely tidy. While a session is isolated in a worktree, Claude Code refuses any tool call that would reach into the main checkout, and the same enforcement covers every subagent that session spawns.

• File edits: an Edit, Write, or NotebookEdit targeting a path in the main checkout is blocked.
• Working directory: a Bash, PowerShell, or Monitor command whose working directory resolves to the main checkout is blocked, and so is one whose working directory cannot be verified as outside it.
• Git redirects: a command that redirects git into the main checkout is blocked, whether via git -C, --git-dir, GIT_DIR, GIT_WORK_TREE, or a cd before the git call.

What a worktree still shares with the main checkout is deliberate: the repository's .git directory (so git commit works from inside a worktree even with sandboxing on), project-scope plugins, and saved permission approvals. Choosing "Yes, don't ask again" in a worktree writes the rule to the main checkout's .claude/settings.local.json, so it applies everywhere and survives the worktree being removed.

Choosing tasks that parallelise

The tooling stops being the constraint almost immediately. Task selection becomes the thing that determines whether parallel agents help or waste your money.

The A/B pattern

One genuinely good use of parallelism is deliberate duplication: give the same hard task to two different models, then pick the better diff. It costs twice as much and is often worth it for something architectural, where the failure mode is a subtly wrong design you will live with for a year.

Sequence anything with a dependency

If task B needs task A's types, running them together produces B guessing at an interface A has not written yet. Merge A first. Parallelism is for independent work, and pretending otherwise wastes two runs instead of one.

The rate limit math

Every session on one account draws from the same rolling five-hour window and the same weekly cap. This is the constraint that surprises people who scale from one agent to four in an afternoon.

Four ways out, in ascending order of cost:

1. Mix models. Put the dependency bump and the test writing on a small model and save the large one for the hard task. This often halves consumption with no quality cost. Set model: haiku in a subagent's config for the mechanical ones.
2. Watch the meter. Add rate_limits.five_hour.used_percentage and rate_limits.seven_day.used_percentage to your status line so the fourth agent is a decision, not an accident.
3. Mix providers. Run one agent on Claude and one on Codex. Two vendors, two independent quotas, and you get a second opinion on architecture for free.
4. Run a second account. Two Max 5x subscriptions cost the same as one Max 20x and give you two independent windows, which is the shape you actually want for parallel work.

Reviewing what comes back

Four agents finishing at once produce four diffs that all need reading. If you skim them because there are four, parallelism has made your codebase worse, not your throughput better. Some structure helps.

Review each worktree on its own

# Manual worktrees
for d in ../myapp-*; do
  echo "=== $d ==="
  git -C "$d" --no-pager diff --stat main...HEAD
done

# Claude-created worktrees
for d in .claude/worktrees/*/; do
  echo "=== $d ==="
  git -C "$d" --no-pager diff --stat main...HEAD
done

Merge in dependency order, not finish order

The agent that finished first is not necessarily the one to merge first. Merge the change other branches will need to rebase onto, then rebase the rest. Rebasing an agent branch is normal and cheap; merging four branches that each assume they are on top of main is not.

Open PRs rather than merging locally

Even solo, one PR per worktree gives you CI per change and a place to leave notes about what the agent did. It also means a bad agent run gets closed rather than reverted.

git -C ../myapp-csv push -u origin feat/csv-export
gh pr create --fill --head feat/csv-export

Cleanup

Worktrees accumulate. A month of this and you have fourteen directories and a branch list you cannot read. Claude Code cleans up most of it, with rules worth knowing so you do not fight them.

• On exit, clean worktree: an unnamed session removes its worktree and branch automatically. A named session asks first.
• On exit, worktree has work: you are prompted to keep or remove. Removing deletes the directory, the branch, and everything in them.
• Non-interactive -p runs: no exit prompt, so nothing is cleaned up. Remove those yourself with git worktree remove.
• Subagent and background worktrees: a periodic sweep removes them once they are older than your cleanupPeriodDays setting, skipping any that still hold changed files, untracked files, or unpushed commits. It never touches worktrees you created with --worktree.
• While an agent runs: Claude runs git worktree lock on its worktree so a concurrent sweep cannot remove it, and releases the lock when the agent finishes.

# Remove a finished worktree and its branch
git worktree remove ../myapp-csv
git branch -d feat/csv-export

# The sweep is keeping one because it still holds work
git worktree remove --force .claude/worktrees/dep-bump

# Clear registrations for directories deleted by hand
git worktree prune

# What is still open?
git worktree list

# Delete local branches already merged into main
git branch --merged main | grep -v '^\*\| main$' | xargs -r git branch -d

Questions people ask

Keep reading