Orpheus
Running many agents

How do you run several Claude Code agents in parallel?

Short answer

Give each agent its own git worktree, so their edits never collide, and its own named tmux session, so you can find it again. Claude Code can do both with claude -w auth --tmux, or you can run git worktree add yourself. Every agent signed in to the same Claude account draws on that account's 5-hour and weekly limits.

On this page

What each agent needs

Two agents in the same folder will edit the same files and trip over each other's half-finished changes. Running several at once comes down to three things:

  • Its own copy of the code. A git worktree is a separate folder with its own branch that shares one repository history with your main checkout.1
  • Its own terminal that outlives you. A named tmux session keeps the agent running when you close the window and lets you come back to it by name.
  • An account with room. Agents on one subscription share its usage limits, so ten agents use them up about ten times as fast as one.3

Set it up with git worktree and tmux

This works with any version of Claude Code and keeps the folders where you can see them.

  1. Create one worktree per task

    Run this from your main checkout. Each command makes a sibling folder on a new branch.2

    cd ~/code/api git worktree add -b auth ../api-auth git worktree add -b billing ../api-billing git worktree list

    A worktree is a fresh checkout. Install dependencies in it and copy any untracked files the project needs, such as .env.

  2. Start one tmux session per worktree

    tmux new -d -s api-auth -c ~/code/api-auth claude tmux new -d -s api-billing -c ~/code/api-billing claude tmux ls

    -d starts the session in the background. Attach with tmux attach -t api-auth to give the agent its task.

  3. Merge, then clean up

    # after the branch is merged git worktree remove ../api-auth git branch -d auth tmux kill-session -t api-auth

    git worktree prune clears records of worktree folders you deleted by hand.2

Or let Claude Code make the worktree

claude --worktree auth (short form -w) creates a worktree under .claude/worktrees/auth/ at the repository root, on a new branch named worktree-auth, and starts Claude in it. Run it again with another name in another terminal for a second agent. Anthropic suggests adding .claude/worktrees/ to .gitignore, and a .worktreeinclude file copies gitignored files such as .env into each new worktree.1

Add --tmux to create a tmux session for that worktree. It uses iTerm2's own panes when they are available, and --tmux=classic forces a normal tmux session.4

claude -w auth --tmux=classic claude -w billing --tmux=classic

Name everything the same way

With five agents running, the fastest way to find one is a name that matches across git, tmux and Claude Code. Pick repo-task and use it everywhere:

One name per agent, used in four places
WhereExample
Worktree folder~/code/api-auth
Branchauth
tmux sessionapi-auth
Claude Code session nameclaude -n api-auth, resumable with claude --resume api-auth
Source: Claude Code CLI reference for -n and --resume. Checked .

Limits are per account and shared by every agent

Running more agents does not give you more usage. Every agent signed in to one Claude account draws on that account's 5-hour and weekly limits, and so does your chat on claude.ai and Claude Desktop.5 Anthropic's agent view docs put it plainly:

Anthropic says

“background sessions consume your subscription usage the same as interactive sessions, so running ten agents in parallel uses quota roughly ten times as fast as running one.”

Manage multiple agents with agent view, code.claude.com · Checked .

Cloud sessions share the same limits.6 Anthropic also notes that the advertised limits for Pro, Max and Ultra "assume ordinary, individual usage of Claude Code and the Agent SDK."7 Anthropic publishes no fixed number of agents per plan. In practice the ceiling is the account's usage and how many results you can review.

If you pay for more than one Claude subscription, you can sign each into its own config folder and start agents under the one you choose. See running two Claude accounts on one machine, and what the terms say before you do.

Watch them without opening every terminal

  • tmux itself. tmux ls lists sessions, and Ctrl-b then s shows a tree with a live preview of each.
  • Claude Code agent view. claude agents opens one screen for your background sessions on this machine, grouped by whether they need input, are working or are done. It is a research preview, and its sessions stop if the machine shuts down.3
  • Claude Squad. A terminal app (AGPL-3.0) that uses tmux for each agent's session and git worktrees for each agent's code, installed as cs.8
  • Orpheus. A hosted view of tmux agents across machines, with each Claude account's usage. It needs tmux and has no free plan.

For a fuller side-by-side, see dashboards for Claude Code agents.

Common questions

How many Claude Code agents can I run at once?

Anthropic does not publish a fixed number. Every agent on an account draws on that account's 5-hour and weekly limits, so the practical ceiling is the account's usage and how much work you can review.

Do I need git worktrees, or can agents share a folder?

Agents that only read code can share a folder. Agents that edit files should each have their own worktree, or they will overwrite each other's changes and run tests against a mix of both.

Does claude --worktree replace git worktree add?

It does the same job for you: it creates the worktree under .claude/worktrees/ on a new branch and starts Claude in it. Use plain git worktree add if you want the folders somewhere else.

Do cloud sessions use the same limits as local agents?

Yes. Anthropic's docs say cloud sessions share rate limits with all other Claude and Claude Code usage on your account, and that running several tasks in parallel uses them up proportionately faster.

Sources

  1. Run parallel sessions with worktreesClaude Code docs, AnthropicUndated · Checked
  2. git-worktree documentationGit projectUndated · Checked
  3. Manage multiple agents with agent viewClaude Code docs, AnthropicUndated · Checked
  4. CLI referenceClaude Code docs, AnthropicUndated · Checked
  5. How do usage and length limits work?Claude Help Center"Updated over a week ago" · Checked
  6. Use Claude Code in the cloudClaude Code docs, AnthropicUndated · Checked
  7. Legal and complianceClaude Code docs, AnthropicUndated · Checked
  8. Claude Squad READMEsmtg-ai on GitHubUndated · Checked