How to run multiple Claude Code agents in parallel

The reason to run agents in parallel is simple arithmetic: a substantial refactor takes an agent ten to forty minutes, and you are not doing anything useful for most of it. Three agents on three projects is three times the throughput — right up until all three need you at once.

There are four approaches that actually work. They differ mostly in how much isolation you get and how much ceremony it costs.

1. Built-in git worktrees (start here)

Two agents editing the same checkout will corrupt each other's work — one rewrites a file the other is mid-way through reasoning about. Git worktrees solve this properly: each session gets its own directory and its own branch, sharing one .git object store.

Claude Code has this built in, so you don't need to manage the worktrees yourself:

# Create a worktree for this session, named automatically
claude --worktree

# Or name it
claude --worktree refactor-auth

# Same, but also spin up a tmux session for it
# (uses iTerm2 native panes when available)
claude --worktree refactor-auth --tmux

Claude Code stores these under .claude/worktrees/<name>/. Each is a real checkout: the agent can run the test suite, install dependencies, and commit without touching what you have open in your editor.

2. Background agents

Since 2.1.x the CLI can start a session detached and hand you back your terminal immediately:

# Start detached, return immediately
claude --bg "migrate the settings store to the new schema"

# Manage what's running
claude agents

This is the lowest-ceremony way to get parallelism: no tmux, no window management, no worktree bookkeeping if you don't want it. The trade is visibility — a background agent that hits a permission prompt is blocked somewhere you aren't looking, which is exactly the failure this whole page builds toward.

3. tmux panes

The manual version, and still the most common setup among people running four or more agents. One pane per project, each running its own claude:

#!/usr/bin/env bash
# fleet.sh — one pane per project
set -euo pipefail

SESSION=agents
tmux new-session -d -s "$SESSION" -c ~/code/api
tmux send-keys -t "$SESSION" 'claude' C-m

for project in web docs infra; do
  tmux split-window -t "$SESSION" -c "$HOME/code/$project"
  tmux send-keys -t "$SESSION" 'claude' C-m
done

tmux select-layout -t "$SESSION" tiled
tmux attach -t "$SESSION"

You get full visibility into every session and a familiar way to jump between them. What you don't get is a signal — you have to *look* at the tiled panes to notice that pane 3 has been blocked for eleven minutes. That's a polling loop implemented with your eyes.

4. Separate clones

Sometimes the right answer is the boring one. If your projects are genuinely unrelated, just clone them into separate directories and run claude in each. No shared git state means no worktree edge cases, no branch collisions, and no shared node_modules surprises. Use --add-dir if a session legitimately needs read access to a sibling project.

Keeping the sessions apart

A few flags matter more once several agents are live at once:

The bottleneck nobody mentions

Here's the thing you discover around week two. Every approach above scales the *work*. None of them scale the *supervision*.

With a conservative permission mode — which is the correct setting, see permission modes explained — each agent stops several times per task and waits for a human. With one agent, you're right there. With four, the interruptions arrive at random from four directions, and the cost isn't the click. It's that you were deep in something else and now you're context-switching four times an hour to answer yes.

So people do the predictable thing and reach for --dangerously-skip-permissions, which converts a supervision problem into a blast-radius problem. That trade is worth reasoning about explicitly rather than drifting into — here's the risk model.

The alternative is to keep the conservative mode and fix the *latency* instead: make being asked cheap enough that a blocked agent costs you seconds rather than the rest of the afternoon. That's a notification problem, and there are several ways to solve it on macOS — hooks that fire a system notification, a statusline you can glance at, or an always-visible overlay that survives fullscreen.

A setup that scales to three or four

1. 01One worktree per long-running task (claude --worktree <name>), reused across tasks rather than created per task, so you pay the dependency install once.
2. 02Name every session (-n) so you can tell them apart in /resume and in your terminal tabs.
3. 03A conservative defaultMode in project settings, plus a deny list covering push, force-delete, and secret reads.
4. 04A Notification or PermissionRequest hook that makes a blocked agent visible without you polling — see the hooks guide.
5. 05A hard cap on concurrency. Three or four is where most people top out, and it's an attention limit, not a machine limit.