How to Run Multiple Claude Code Agents in Parallel

You can run multiple Claude Code agents in parallel in several genuinely different ways, and Claude Code now ships most of them itself. The right one depends on whether you want independent code changes, delegated work inside one conversation, sessions you hand off and check back on later, or remote jobs that keep running away from your machine.

The practical answer is:

• Use claude --worktree when you want independent local tasks, each in its own isolated checkout, driven by you in separate terminals.
• Use agent view (claude agents) when you want to dispatch several background sessions and watch them from one screen.
• Use subagents when one task needs bounded supporting work — research, review, tests — returned as a summary.
• Use cloud sessions (claude --cloud) when the work should run remotely rather than on your computer.
• Use Parallel Code when you want a visual dashboard and the option to run Claude Code beside Codex, Gemini, Copilot, or Antigravity.

For independent local tasks that change code, give every task its own working directory and Git index — usually a worktree. Running several write-capable Claude Code sessions in one checkout is not isolation.

Disclosure: Parallel Code is our product. Claude Code’s native parallel features have grown substantially, and this guide covers them first because for many workflows they are now the shortest path.

The ways to run Claude Code in parallel

Anthropic’s own comparison of parallel approaches separates the coordination style from the isolation mechanism. That distinction is the one worth holding onto: worktrees decide where the files live, and the approaches below decide who drives the work.

Approach	Best for	Isolation boundary	Main tradeoff
claude --worktree	Independent local tasks you drive yourself	Managed git worktree and branch per session	You switch terminals to steer each one
Agent view	Handing off several tasks and checking back	Own worktree before file edits by default in Git repos	Research preview; each session bills separately
Subagents	Research, review, and other supporting work	Fresh context window; a worktree only if requested	Not a reviewable branch per subagent
Cloud sessions	Remote, asynchronous work	Anthropic-managed VM per session	Starts from a GitHub clone or uploaded repository bundle
Agent teams	Coordinated workers that message each other	None by default — partition files yourself	Experimental, off by default, token-heavy
Parallel Code	Visual orchestration or mixed agents	Managed branch and worktree by default	Another local app in the workflow

These are complementary. You can run two independent worktree sessions while each one delegates read-only analysis to subagents. What matters is knowing which layer is providing the isolation.

Option 1: Run parallel sessions with claude --worktree

Claude Code creates and manages worktrees for you. Pass --worktree (or -w) with a name:

claude --worktree feature-auth

By default this creates the worktree under .claude/worktrees/<name>/ at your repository root, on a new branch named worktree-<name>. Run the same command with a different name in a second terminal to start an isolated parallel session:

claude --worktree fix-pagination

If you omit the name, Claude Code generates one such as bright-running-fox. The repository needs at least one commit, since a worktree is created from an existing commit. Add .claude/worktrees/ to your .gitignore so worktree contents don’t show up as untracked files in your main checkout.

Interactive runs require workspace trust. If you have never run Claude in the directory before, run claude once there to accept the trust dialog first.

Choose what the worktree branches from

With the default "fresh" setting, new worktrees normally branch from your repository’s default branch on the remote, not from your current work. If no remote is configured, or the remote default cannot be resolved, Claude Code falls back to your current local HEAD. To choose local HEAD deliberately, set worktree.baseRef in settings:

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

The setting accepts only "fresh" (default) and "head" — you cannot point it at an arbitrary branch name. To start from a specific existing branch, create the worktree with git directly. To branch from a pull request, pass its number, quoted so your shell doesn’t treat # as a comment:

claude --worktree "#1234"

Carry gitignored files into each worktree

A worktree is a fresh checkout, so untracked files like .env are not present. Add a .worktreeinclude file at your project root, using .gitignore syntax, to copy them automatically:

.env
.env.local
config/secrets.json

Only files that match a pattern and are gitignored are copied, so tracked files are never duplicated. Be conservative with this list: every copied secret becomes available in another task environment. You will usually also need to install dependencies in the new worktree before tests will run.

What Claude Code blocks while you are in a worktree

Isolation here is enforced, not merely conventional. While a session is in a worktree, Claude Code blocks four categories of tool call: file edits targeting the main checkout, commands whose working directory resolves to the main checkout, git commands redirected at the main checkout through git -C, --git-dir, GIT_DIR, or a cd, and commands whose shape it cannot verify stays inside the worktree. That last check refuses constructs it can’t trace without running them, such as brace expansion and heredocs with unquoted delimiters. It cannot be turned off.

The same enforcement covers every subagent spawned from an isolated session.

Cleanup

When you exit an interactive worktree session, Claude Code checks for work that removal would delete. A clean unnamed session’s worktree and branch are removed automatically; a named session prompts you first. If the worktree holds changes, untracked files, or new commits, Claude Code asks whether to keep or remove it.

Non-interactive -p runs have no exit prompt, so they don’t clean up. Remove those with git worktree remove, adding git worktree unlock first if git refuses because the worktree is locked.

What worktrees still share

A worktree gets its own files and branch, but it shares the repository’s .git directory, project-scope plugins, and, in the usual repository-root configuration, saved permission approvals with the main checkout. Choosing “Yes, and don’t ask again” for a Bash command then saves the rule to the main checkout’s .claude/settings.local.json, so it applies throughout the repository and survives the worktree’s removal. On Windows and in other cases where Claude Code does not use the repository root for approvals, the rule stays with that worktree instead.

Worktrees also do not automatically give each session:

• A different development-server port
• A separate database
• Independent Docker container names or volumes
• Separate external service accounts
• Independent subscription or rate limits

If two tasks both start a server on port 3000 or point migrations at the same database, they can still interfere. Filesystem isolation is necessary, but it is not complete environment isolation. The same model applies whichever agent you use; our guide to git worktree isolation for parallel agents covers the underlying mechanics.

When to manage worktrees yourself

Create worktrees with git directly when you need a specific existing branch or a location outside the repository:

git worktree add ../project-feature-a -b feature-a
cd ../project-feature-a
claude

List them with git worktree list and remove them with git worktree remove <path>. If worktrees are new to you, start with git worktrees explained.

Option 2: Dispatch background sessions with agent view

Worktree sessions still expect you to sit in each terminal. Agent view inverts that: you dispatch work, and step in only when a session needs you. Open it with:

claude agents

Type a prompt and press Enter to dispatch a background session — a full Claude Code conversation that keeps running without a terminal attached. Each prompt starts its own session. You can also dispatch from your shell:

claude --bg "investigate the flaky test"
claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"
claude --bg --agent code-reviewer "address review comments on PR 1234"

Or send the session you are already in to the background with /bg, or copy it while keeping the original with /fork.

By default in a Git repository, Agent view moves each dispatched session into its own worktree before it edits files. It skips that move when the session is already in a linked worktree or worktree.bgIsolation is set to "none"; outside Git, isolation requires a configured WorktreeCreate hook.

Sessions are grouped by state — working, needs input, idle, completed, failed, stopped — so a session waiting on a permission prompt is visible instead of silently stalled. Press Space to peek at a row’s question or result without opening the full transcript, and reply from there. Press Enter to attach; detaching never stops the session.

From the shell you can manage sessions without the interface:

claude agents --json     # list sessions as JSON
claude attach <id>       # attach in this terminal
claude logs <id>         # print recent output
claude stop <id>         # stop a session

Two caveats. Agent view is a research preview, so the interface and shortcuts may change. And each background session consumes your subscription quota independently — the row summaries themselves use billed model requests.

Option 3: Delegate to subagents

Subagents parallelize work inside one session. The main conversation delegates bounded work, waits, and combines the results. Each regular subagent runs in a fresh context window and returns a summary, which keeps noisy search results and file reads out of your main thread.

You can ask for one in plain language:

use a subagent to investigate how our auth system handles token refresh

Or define a reusable one as a Markdown file with YAML frontmatter in .claude/agents/ for the project, or ~/.claude/agents/ for all projects. Project subagents should be checked into version control so the team shares them:

---
name: code-reviewer
description: Reviews changes for correctness, security, and test gaps
tools: Read, Grep, Glob
---

Review the diff and return one severity-ranked report with file references.

Restricting tools to Read, Grep, Glob is what makes a reviewer genuinely read-only — the prompt documents the intent, but the tool list enforces it. Subagents can write and edit code by default.

Claude Code runs up to 20 subagents concurrently by default, adjustable with CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, and limits nesting to three layers deep.

Give write-heavy subagents their own worktrees

For subagents that change code, add isolation: worktree to the 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.

Each such subagent gets a temporary worktree, removed automatically when it finishes without changes. Note that subagent worktrees use the same base as --worktree: with the default "fresh" setting, they normally branch from your repository’s remote default branch rather than your current HEAD, with the same local-HEAD fallback described above. If you are isolating subagents that need to operate on in-progress work, set worktree.baseRef to "head".

Use subagents when one task benefits from several independent investigations and the outputs should be synthesized into one answer. Use separate top-level worktree sessions when each result should produce its own independently reviewable branch.

Option 4: Run Claude Code through Parallel Code

Native worktrees and agent view cover a lot of ground. Parallel Code covers a different axis: a native desktop GUI, and one dashboard for Claude Code alongside other agents.

The setup is:

1. Install and authenticate Claude Code normally.
2. Install the latest Parallel Code release.
3. Open your repository, create a task, select Claude Code, and submit the prompt.
4. Repeat for the other independent tasks.

By default, an isolated task gets its own branch and worktree; Direct mode and non-Git folders are the exceptions. The diff view lets you review each result before merging or discarding it.

Review one shared-state setting before launching. Parallel Code detects ignored root entries, preselects its built-in defaults such as .env and node_modules, and symlinks the selected paths into task worktrees. Deselect secrets, caches, or dependencies that must stay private or independently mutable. Note this is a symlink, not a copy — unlike .worktreeinclude, edits propagate back.

Parallel Code is most useful when you want to:

• Run Claude Code beside Codex CLI, Gemini CLI, Copilot CLI, or Antigravity CLI in one place
• Race several agents on the same task and compare their diffs
• Review diffs in a GUI rather than a terminal
• Monitor long-running sessions from your phone

If you only use Claude Code and live in the terminal, claude --worktree and claude agents may be all you need, and they are the shorter path. The case for a separate orchestrator is strongest when you deliberately run more than one vendor’s agent — see using Claude Code and Codex together — or when you want a visual review surface.

Option 5: Dispatch parallel cloud sessions

Claude Code on the web runs tasks on Anthropic-managed infrastructure. It is in research preview for Pro, Max, and Team users, and for Enterprise users with premium seats or Chat + Claude Code seats.

Each --cloud command creates its own independent session, so several run simultaneously:

claude --cloud "Fix the flaky test in auth.spec.ts"
claude --cloud "Update the API documentation"
claude --cloud "Refactor the logger to use structured output"

Monitor them with /tasks in the CLI, or from claude.ai and the mobile app.

With GitHub access configured, the cloud VM clones your current directory’s GitHub remote at your current branch, not your local checkout. Push local commits first, or the session will not see them. If GitHub access is unavailable, Claude Code can instead upload a local repository bundle that can include tracked uncommitted changes; untracked files are omitted, and credential-like files have additional exclusions. A task that only works because of an undocumented local dependency may still behave differently in the cloud.

A useful pattern is to plan locally and execute remotely. Work out the approach in plan mode, commit the plan, then dispatch:

claude --permission-mode plan
# ...agree on the approach, save and push it...
claude --cloud "Execute the migration plan in docs/migration-plan.md"

When a session finishes, pull it into your terminal with claude --teleport <session-id> to continue locally. Teleport needs a clean working directory, the same repository, the branch pushed to the remote, and the same claude.ai account.

Cloud sessions share rate limits with all your other Claude usage, and running several in parallel consumes them proportionately. There is no separate compute charge for the VM.

What about agent teams?

Agent teams coordinate multiple Claude Code sessions with a lead, a shared task list, and inter-agent messaging. They are experimental and disabled by default, enabled with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

They are worth knowing about, but they are not the default answer for parallel code changes, for one specific reason: agent teams don’t isolate teammates in worktrees. Two teammates editing the same file will overwrite each other, so you have to partition file ownership yourself. Anthropic’s own guidance is to start with research and review tasks rather than parallel implementation, and to begin with three to five teammates.

They also use significantly more tokens than a single session, since each teammate is a full Claude instance with its own context window. For independent code changes that each need a reviewable branch, worktree sessions remain easier to reason about.

How to choose

First decide who should be driving:

• You drive each task → claude --worktree in separate terminals
• You hand off and check back → agent view (claude agents)
• Claude delegates within one conversation → subagents
• The work should run away from your machine → claude --cloud
• You want a GUI, or mixed agents from different vendors → Parallel Code

Then decide whether the tasks may edit the same files. For independent tasks, choose a worktree-isolated approach. Agent-team teammates are the exception: partition file ownership yourself, run the edits sequentially, or reconsider whether the work should be one task.

For a first attempt, two independent worktree sessions are enough. Add concurrency only when the work splits cleanly and review is not already the bottleneck.

A safe parallel Claude Code workflow

1. Start from a baseline you can name

Know what each task branched from. --worktree and subagent worktrees normally use the remote default branch, with a local-HEAD fallback when that remote base is unavailable. Cloud sessions with GitHub access clone your pushed branch, while the local-bundle fallback can include tracked uncommitted changes. Check the mode instead of assuming local state is shared.

2. Give each task one observable outcome

“Improve the API” invites overlapping edits. “Reject invalid pagination values without changing valid responses” has a clear boundary and a verification path. Our AI coding agent prompt template is built for this kind of brief.

3. Split by ownership, not by intention

Two prompts can sound different while still changing the same controller, schema, and test file. Map the likely files before starting. The guide to splitting a feature into parallel agent tasks covers how to find safer seams.

4. Keep permissions proportionate

Every concurrent agent increases how many commands can run at once. Worktree isolation constrains the filesystem; it does not protect secrets, databases, or remote systems from an over-permissioned process. Agent permissions and sandboxing covers which settings actually enforce a boundary. Remember that a repository-scoped “don’t ask again” approval granted inside a worktree can apply to every checkout in that repository.

5. Review before integrating

Merge one result, verify the combined baseline, then move to the next — the integration workflow for parallel branches covers merge order and the semantic conflicts that survive a clean merge. Pause an agent and commit or stash its work before changing the branch underneath it. The review burden grows with output volume even when execution time falls — use a consistent AI-generated code review checklist.

6. Watch aggregate usage

Each session, subagent, and teammate performs its own model work, including repeated context. Parallel execution concentrates that usage into a shorter period. The cost guide for parallel agents explains where the money actually goes.

Frequently asked questions

Can Claude Code run multiple agents at the same time?

Yes, in several ways. You can run independent sessions with claude --worktree, dispatch background sessions from agent view, delegate to as many as 20 concurrent subagents by default inside one session, or start multiple cloud sessions with claude --cloud. These solve different problems, so “multiple agents” does not automatically mean “multiple isolated branches.”

Does Claude Code create a worktree automatically?

It depends on the surface. claude --worktree creates one explicitly. By default in a Git repository, Agent view moves each dispatched background session into a worktree before it edits files. In the desktop app, every new session gets its own worktree automatically. A plain claude in your terminal does not — it works in your current checkout.

Should I use worktrees or subagents?

Use worktrees when each task should produce an independent code change you can review, keep, or discard. Use subagents when one parent task needs parallel supporting work and one synthesized result. You can combine both: add isolation: worktree to a subagent that writes code.

Do worktrees prevent merge conflicts?

No. They prevent concurrent sessions from modifying the same working copy, but overlapping edits still conflict at merge time and semantic incompatibilities can merge cleanly and fail only at runtime. Merging work from parallel AI agents covers how to find both before they reach main.

What is the best way to run multiple Claude Code agents on Linux?

All of the native options work on Linux: claude --worktree, claude agents, subagents, and cloud sessions. For a native GUI, Parallel Code ships Linux builds. Agent teams’ split-pane display mode requires tmux or iTerm2, but its default in-process mode works in any terminal. See our survey of AI coding agents on Linux for the wider picture.

Can I run Claude Code and Codex in parallel on the same repo?

Yes, provided each has its own working copy. The isolation requirement is identical regardless of vendor. Using Claude Code and Codex together covers four workflows for the combination, and running multiple Codex agents in parallel covers Codex’s own equivalents to the options above.

Start with two tasks

The fastest way to learn this workflow is not to launch ten agents. Pick two small, independent tasks, start each in its own worktree, and review and integrate both before increasing the concurrency.

Once that loop feels routine, choose the surface that removes the most friction from your setup — a second terminal, agent view, or a dashboard — while keeping the task boundaries, permissions, and review discipline that made the first two work.