How to run Claude Code agents in parallel

What does “parallel agents” mean in Claude Code?

Anthropic documents five ways Claude Code takes on several tasks at once, distinguished by who coordinates the work. This guide covers the two you can use today with no extra setup or orchestration (subagents and agent view) plus worktrees, which give either one a checkout of its own.

Anthropic marks three of those as not yet general: agent teams is experimental and disabled by default, projects is in public beta on Pro and Max, and agent view itself is a research preview. Agent teams and dynamic workflows are not covered further here; Anthropic documents them on its own agent teams and dynamic workflows pages.

Running multiple Claude Code sessions covers the wider ground, including terminal tabs, tmux, and what parallel sessions cost you in quota.

Route 1: subagents inside one session

A subagent is a worker Claude delegates a side task to in its own context, and it returns a summary to the conversation that spawned it. The search results, logs and file contents it read stay out of your main conversation, so your context stays about the task rather than about the looking.

Claude delegates on its own when a task fits, and the documented case for a subagent is a task whose verbose output you do not need in your main context. You can also name one explicitly, and you can write your own in a subagent file: .claude/agents/ scopes it to the current project and ~/.claude/agents/ to all of yours. The file uses YAML frontmatter for configuration, such as a model, the tools it may use and the instructions it follows, followed by the system prompt in Markdown.

Several subagents can be running at once, and there is a hard ceiling on that: when 20 are running in a session, Claude Code refuses to spawn another and tells Claude not to retry, and sessions with ultracode active are exempt from the limit. Set CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS to change it. Nothing limits how many a session spawns across its life, only how many run at the same moment.

Subagents are not isolated from each other by default; they share your working copy. Subagents a session spawns can each get their own worktree, which is the section below.

/batch is the packaged version for one large change: Claude researches the codebase, decomposes the work into 5 to 30 independent units and presents a plan. Once you approve it, Claude spawns one background subagent per unit, each in its own worktree.

Route 2: agent view, one screen for background sessions

Agent view is opened with claude agents. It is one screen showing every session Claude Code is running in the background, each as a row, and you dispatch new work by typing a prompt into it. Every prompt you enter there starts its own session, which is how you run several side by side.

Driving it from the keyboard

Select a row with the arrow keys. Space opens a panel showing that session's latest output or the question it is waiting on, and you type a reply and press Enter to send it without leaving the screen. Enter or → attaches instead, handing the terminal to that session's full conversation; ← on an empty prompt detaches and returns to the table. To move a session you already have open into the list, run /bg inside it.

What the rows tell you

Each row carries a state: Needs input means Claude is waiting on something only you can give it, and Failed means the task ended with an error. Working, Idle, Completed and Stopped are the others. The shape of the icon says whether the process is still running or has exited and can be restarted from its saved conversation.

The list shows every background session you have started, across all your projects, whatever directory you opened it from; --cwd narrows it to one project and Ctrl+S groups it by directory. A separate supervisor process runs the sessions, so closing agent view or your shell does not stop them, and they survive the machine sleeping. Read the same state from a script with claude agents --json.

A session waiting on an answer looks like one that is working if all you have is a count of running sessions. Agent view's state column separates the two.

Route 3: worktrees, so two agents never share a file

A git worktree gives a session its own checkout on its own branch. Pass --worktree (or -w) with a name and Claude Code creates one under .claude/worktrees/<name>/ at the repository root, on a new branch called worktree-<name>. Two sessions then have two directories, and their writes cannot collide.

New worktrees branch from the repository's default branch on the remote, not from wherever you happen to be, so a worktree starts from a clean tree that matches the remote. Set worktree.baseRef to head in settings to branch from your current work instead, which is what you want when a subagent has to build on an unpushed commit.

A worktree is a fresh checkout, so untracked files are not in it. To carry the gitignored ones you need, .env say, list them in a .worktreeinclude file at the project root. The file uses .gitignore syntax, and only files that match a pattern and are gitignored are copied, so a tracked file is never duplicated.

Claude Code runs a periodic sweep, a background tidy-up on a retention timer, that removes the worktrees it created for subagents and background sessions. It leaves one alone when it still holds work, when it belongs to a --worktree session you have not backgrounded, or when you created it yourself with git worktree add.

A session dispatched from agent view starts in your working directory and is moved into a worktree of its own before it edits anything, so parallel sessions read the same checkout but each writes to its own; subagents it spawns inherit that isolation. To turn the move off in a repository where worktrees are impractical, set worktree.bgIsolation to "none" in the project's .claude/settings.json.

What breaks first when agents run in parallel?

Two things, and neither is the machine. Every session counts against your subscription usage on its own, so ten agents spend quota roughly ten times as fast as one; and a session waiting on you looks like a session working once there are six of them. On a Claude Pro or Max plan, the monthly spend limit for usage credits is in Settings > Usage on claude.ai. Running multiple sessions works through the rest.

Where a desktop manager fits

Claude Code's own parallel routes are Claude sessions, and Anthropic's docs open with exactly that: "In every approach the workers are Claude sessions." A manager is for what falls outside them: a second harness in the same list, a window instead of a terminal, and one place that collects what needs you across every project.

Omniscio is a desktop app built around that list. Any model, any harness — Claude Code, Codex, OpenCode, Devin, Pi, and Hermes all supported.

Two behaviours are worth knowing before you assume a default. Per-session git worktree isolation ships off and turns on for one session, one project or the whole app; a session can also choose it per session. It is on by default only for the harnesses that auto-approve every tool call (OpenCode, Pi, Gemini, Grok and Antigravity), which are also harnesses Omniscio runs alongside the rest. A folder that is not a git repository always runs in place, since there is nothing to branch from. A per-session spend cap limits sessions billed through a pay-per-use API key; it never applies to Pro or Max subscriptions.

The free plan covers 8 projects and 10 agents at once, and Pro is $20/month or $192/year. Teams running several harnesses can read how a session gets its own copy of a project in the library.