How to Run Claude Code Subagents in Parallel Safely

You put two subagents to work at the same time: one changes the callers, the other changes the interface definition. Both report done quickly, and each one's tests pass. Then you merge the changes: the callers pass three arguments, the interface accepts two, and the module won't compile.

Parallel work saves time only if the tasks really are independent. By default, several subagents work in the same project directory, so writing the same file means overwriting each other. Even with separate files, tests can fight over the same port or database. Even with worktrees isolating file copies, code that passes on its own still won't fit together if the interface was never agreed first.

There are three safe ways to split parallel work, in order of preference:

several agents do read-only research, and the main session makes the changes after combining their findings;
write tasks are split by directory or file, with exactly one agent responsible for each file;
when agents genuinely need to change the same area separately, isolate file copies with Git worktrees.

Whichever you choose, settle shared decisions in sequence first, and run cross-module verification again after integration. We'll go through each option, then cover foreground versus background.

01 First, Decide Whether It Can Run in Parallel

Independent research suits parallel work, such as checking auth, the database, and tests separately. Tasks that depend on each other still run in sequence.

Suitable for parallel work:
  Auth call-chain research   ─┐
  Data model impact analysis ├─> combined by the main session
  Test failure grouping      ─┘

Not suitable as-is:
  Settle the interface design -> implement the service -> add tests

Subagents share the project working directory by default. Writing the same file in parallel can overwrite each other's changes, and tests can fight over ports and databases. Even for read-only research, confirm that resources and assumptions are independent. The Claude Code subagents documentation states that a subagent starts in the main conversation's current working directory; giving it an isolated copy of the repository requires a worktree.

Whether a task should go to a subagent at all comes down to three questions about being self-contained, high-output, and independent; see when to use subagents in Claude Code.

02 Three Ways to Split, in Order

Safe parallel work, in order of preference:

Several agents do only read-only research, and the main session makes the changes after combining the findings.
Write tasks are split by directory or file, with each file having exactly one owner.
When agents need to change the same area independently, enable Git worktree isolation for them:

isolation: worktree

The first option is the safest: research runs in parallel, and writes happen in only one place, the main session, so nothing gets overwritten. How to check research findings before using them is covered in briefing a subagent and checking its findings.

The second option needs "who owns which file" spelled out, in each subagent's delegation message.

03 A Worktree Isolates Only Files

With a worktree, file copies are separate, and it's easy to assume the tasks are fully isolated. The database, ports, and external accounts may still be shared, and the default base may not match the main session's current HEAD.

The subagents documentation describes isolation: worktree this way: the subagent runs in a temporary git worktree with an isolated copy of the repository, branched by default from your default branch rather than the parent session's HEAD. If you're halfway through a feature branch, the subagent may get older code from the main branch. Confirm these things before starting.

When implementation results come back, you still have to review and integrate them. Isolated files don't prove the two versions of code are compatible.

04 Settle Shared Interfaces in Sequence

Different files can still share an interface, for example when callers and the interface definition use different parameters. Settle the interface in sequence first, implement separately, and check the integrated result at the end.

The compile failure in the opening came from running "define the interface" in parallel too. The right order: the main session settles the interface signature, then two subagents implement the callers and the interface internals separately.

The same applies inside a full fix: the auth call chain, data model, and test failures can be investigated separately, while the revocation protocol and shared data structures should be decided together after the findings are combined. When inputs and writes are independent, split the work using ownership and worktrees. After integration, rerun cross-module verification; subtasks passing on their own don't replace overall acceptance.

05 Foreground or Background

If the main flow is waiting on the result, use the foreground. If you want to keep working on something independent, use the background, which suits searches, tests, and checking references.

The Claude Code best practices note that the subagents Claude starts run in the background by default, so your main conversation keeps moving. The subagents documentation adds the controls: in interactive sessions, fork mode is on by default and subagents run in the background; to have Claude wait for a subagent, turn fork mode off; once it's off and Claude is waiting, press Ctrl+B to move the subagent to the background.

A few things to remember:

If the next step depends on its conclusion, the main session still has to wait. Background means running concurrently; whether it finished needs checking separately.
Background subagents get fewer built-in tools than foreground ones, and the docs list which tools they keep.
Background tasks are still governed by permissions. Approving one tool call allows only that operation, not the subagent's whole plan.

Avoid bypassPermissions in ordinary project agents. If you truly need unattended execution, first restrict the filesystem and network with a container or VM, then use explicit allow rules or dontAsk mode so unapproved actions fail.

Parallel work is fast because the tasks don't depend on each other. Settle shared decisions in sequence first, then split by file. Subtasks passing on their own is only the starting point; overall acceptance means rerunning verification after integration.