Claude Code Split-and-Merge Pattern: How Sub-Agents Run in Parallel Within One Session

What the Split-and-Merge Pattern Actually Does

If you’ve used Claude Code for anything beyond simple one-off tasks, you’ve probably hit a wall: some problems are just too big, too parallel, or too multi-dimensional to hand off as a single prompt. The split-and-merge pattern solves this.

At its core, the pattern is straightforward. A parent Claude agent — the orchestrator — breaks a large task into discrete subtasks, fans them out to multiple sub-agents running simultaneously, then collects and merges the results. All of this happens within a single Claude Code terminal session, without spinning up separate processes or coordinating across different systems manually.

This is how multi-agent workflows in Claude get genuinely useful for production-level work: not by making one agent smarter, but by running several agents in parallel and combining what they find.

---

How Sub-Agents Work Inside Claude Code

Claude Code ships with a built-in Task tool. When an orchestrator agent calls Task, it spawns a new sub-agent with its own context, instructions, and toolset. That sub-agent runs independently, does its work, and returns a result.

The key mechanic is that multiple Task calls can be issued simultaneously. The orchestrator doesn’t have to wait for one sub-agent to finish before starting the next. It can fan out up to 10 sub-agents at once, all operating in parallel.

What each sub-agent can do

Each sub-agent has access to the same tools Claude Code provides at the top level:

• Read and write files
• Run shell commands and scripts
• Execute code and inspect output
• Search the web or query APIs
• Spawn their own sub-agents (enabling nested hierarchies)

Sub-agents don’t share memory or context with each other — they only see what the orchestrator passes to them in their instructions. This isolation is intentional. It keeps sub-agents focused and prevents cross-contamination of results.

What the orchestrator does

The orchestrator’s job has two distinct phases:

1. Fan-out — Decompose the task, write clear instructions for each sub-agent, and issue all Task calls
2. Merge — Wait for all sub-agents to return, evaluate results, resolve conflicts, and synthesize a final output

The orchestrator is where the reasoning lives. Sub-agents are workers. This division makes the pattern composable and predictable.

---

A Concrete Example: Auditing a Large Codebase

Say you need to audit a codebase with 40 modules for security issues, code quality problems, and outdated dependencies — all at once.

Without the split-and-merge pattern, you’d either process modules sequentially (slow) or run Claude once with too much context (expensive, error-prone).

With the pattern:

1. The orchestrator reads the top-level directory structure
2. It groups modules into 10 batches
3. It spawns 10 sub-agents simultaneously, each with instructions to audit their assigned batch
4. Each sub-agent reads files, runs lint tools, checks import versions, and returns a structured report
5. The orchestrator receives 10 reports and merges them into a single audit document, deduplicating findings and ranking issues by severity

What might take an hour sequentially can complete in the time it takes the slowest sub-agent to finish — often a fraction of the total.

---

When to Use Split-and-Merge vs. a Single Agent

The pattern isn’t always the right choice. Here’s a practical way to think about it.

Use split-and-merge when:

• The task has clearly separable subtasks with minimal interdependence
• You’re working with large volumes of data, files, or content
• You need multiple independent analyses or perspectives on the same problem
• Subtasks can run in parallel without needing each other’s outputs first
• You want to compare or cross-reference results across different inputs

Stick with a single agent when:

• The task requires sequential reasoning where each step builds on the last
• Context from earlier steps is essential to later steps
• The problem is small enough to fit in a single context window without quality degradation
• Coordination overhead would outweigh the parallelism benefit

The overhead of orchestrating sub-agents isn’t zero. If you’re analyzing a single file or writing a short document, a single agent is faster and cleaner.

---

Setting Up the Pattern in Practice

Here’s what a working split-and-merge implementation looks like in Claude Code.

Step 1: Define the orchestrator’s decomposition logic

The orchestrator needs clear instructions about how to split work. Be explicit in your system prompt. Vague instructions produce uneven splits and inconsistent sub-agent behavior.

Example orchestrator prompt:

You are an orchestration agent. Your job is to:
1. Analyze the input task
2. Break it into N independent subtasks (where N ≤ 10)
3. For each subtask, spawn a Task with a self-contained instruction set
4. Wait for all tasks to complete
5. Merge the results into a unified output following the format below

The format specification in step 5 is critical. Sub-agents need to return results in a consistent structure so the merge step works cleanly.

Step 2: Write tight sub-agent instructions

Each sub-agent instruction should be self-contained. Assume the sub-agent knows nothing except what you tell it. Include:

• The specific scope (e.g., “Analyze only the files in /src/auth/”)
• The task to perform
• The exact output format expected
• Any constraints or context required

Avoid passing large blobs of context you don’t need. Sub-agents have their own context windows, and filling them with irrelevant information degrades performance.

Step 3: Handle the merge carefully

Merging is where most implementations get sloppy. Consider:

• Conflict resolution — What happens when two sub-agents return contradictory findings?
• Deduplication — Sub-agents working on adjacent areas may flag the same issue
• Ranking and prioritization — Raw concatenation isn’t a merge; you need the orchestrator to reason about the combined output
• Completeness checks — Did every sub-agent return a result, or did some fail silently?

Build explicit merge logic into your orchestrator prompt. Don’t assume it will figure this out on its own.

Step 4: Test with smaller fan-outs first

Start with 2–3 sub-agents before scaling to 10. Verify that:

• Instructions are clear enough for sub-agents to act independently
• Output formats are consistent
• The merge step produces coherent results
• Error handling works when a sub-agent fails or returns unexpected output

Debugging a 10-agent parallel run is significantly harder than debugging a 3-agent one.

---

The 10-Agent Limit and Context Considerations

Claude Code currently supports up to 10 simultaneous sub-agents per orchestrator. This isn’t an arbitrary cap — it reflects practical constraints around context window usage, cost management, and result coherence.

Each sub-agent consumes its own context. Running 10 sub-agents in parallel means you’re effectively running 10 Claude instances simultaneously. Costs scale accordingly. For large tasks, it’s worth sizing your subtasks so each sub-agent does meaningful work, not trivial operations that don’t justify the overhead.

On context window depth: if sub-agents themselves spawn sub-agents (nested orchestration), the hierarchy can get complex fast. Each level of nesting adds latency and coordination overhead. For most use cases, a single orchestrator with 10 sub-agents is sufficient. Reserve nested orchestration for genuinely complex multi-phase workflows.

---

Common Mistakes and How to Avoid Them

Underspecified sub-agent instructions

The most frequent failure mode. If your sub-agent instructions are ambiguous, you’ll get inconsistent output formats that are hard to merge. Write sub-agent prompts like you’re writing API documentation — precise, complete, unambiguous.

Over-splitting simple tasks

Splitting a 5-file codebase into 5 sub-agents isn’t an optimization — it’s unnecessary complexity. Reserve the pattern for tasks where parallelism meaningfully reduces time or improves quality.

Ignoring sub-agent failures

Sub-agents can fail, time out, or return malformed output. Your orchestrator needs to handle this gracefully. At minimum, check that all expected sub-agents returned before proceeding to the merge step.

Tight coupling between sub-tasks

If subtask B needs the output of subtask A to function, they can’t run in parallel. Mixing parallel and sequential dependencies in the same fan-out layer creates hard-to-debug ordering problems. Map your task dependencies before deciding what to parallelize.

No output schema enforcement

Without a defined output schema, sub-agents will return results in whatever format feels natural to them. Define the schema explicitly in the sub-agent instructions and have the orchestrator validate outputs during merge.

---

Where MindStudio Fits for Teams Without Custom Dev Resources

Claude Code’s split-and-merge pattern is powerful, but it assumes you’re comfortable writing orchestration logic in a terminal, managing sub-agent prompts as code, and debugging parallel execution manually.

For teams that want the same parallelism and multi-agent coordination without building it from scratch, MindStudio offers a visual no-code builder where you can design multi-step agent workflows that mirror this pattern — without writing orchestration prompts by hand.

Specifically, the Agent Skills Plugin (@mindstudio-ai/agent) lets Claude Code agents call MindStudio workflows directly as typed method calls. That means you can build the complex merge logic, notification routing, or data transformation steps visually in MindStudio, then invoke them from within a Claude Code sub-agent via something like agent.runWorkflow().

This is useful when your split-and-merge pattern includes steps that touch external systems — sending emails, writing to a CRM, generating reports, posting to Slack. Instead of wiring each integration manually inside Claude Code, you expose them as callable MindStudio workflows and let your sub-agents use them as clean function calls.

MindStudio has 200+ AI models and 1,000+ pre-built integrations available out of the box, so the infrastructure layer is already handled. You can try it free at mindstudio.ai.

---

Practical Use Cases for the Pattern

Parallel test generation

Fan out to sub-agents that each write unit tests for a different module. Merge into a single test suite. Works well because test generation per module is independent.

Multi-source research synthesis

Assign each sub-agent a different source or document. Each returns a structured summary. The orchestrator synthesizes findings, identifies agreement and contradiction, and produces a unified brief.

Large-scale content review

Pass different sections of a long document or multiple documents to sub-agents for consistency checks, fact verification, or style review. Merge flags into a prioritized editing queue.

Competitive analysis

Give each sub-agent a competitor to analyze against a defined framework. The orchestrator merges findings into a comparison matrix.

Parallel code generation

Split a feature into independent components (e.g., API layer, data model, UI component, tests). Sub-agents generate each piece. The orchestrator reviews for integration issues and assembles the final implementation.

---

FAQ

What is the split-and-merge pattern in Claude Code?

The split-and-merge pattern is a multi-agent workflow where a parent (orchestrator) agent breaks a task into subtasks, fans them out to multiple sub-agents running in parallel, and then collects and merges the results. In Claude Code, this is implemented using the built-in Task tool, which lets the orchestrator spawn up to 10 sub-agents simultaneously within a single terminal session.

How many sub-agents can Claude Code run in parallel?

Claude Code supports up to 10 simultaneous sub-agents per orchestrator. Each sub-agent runs with its own context and toolset independently of the others. Sub-agents can themselves spawn additional sub-agents, enabling nested multi-level orchestration, though this adds complexity and latency.

Do sub-agents in Claude Code share memory or context?

No. Sub-agents are isolated from each other. Each sub-agent only knows what the orchestrator passes to it in its initial instructions. They cannot read each other’s outputs directly. All cross-agent communication goes through the orchestrator, which collects results and synthesizes them during the merge phase.

What kinds of tasks benefit most from parallel sub-agents?

Tasks that have clearly separable, independent subtasks benefit most. Examples include auditing multiple files or modules, analyzing multiple documents, generating tests for different components, or performing the same analysis across different data inputs. Tasks with sequential dependencies — where step B requires step A’s output — are less suited for parallelism.

How does Claude Code handle sub-agent failures?

Sub-agents can fail or return unexpected output. Claude Code itself doesn’t automatically retry failed sub-agents. Your orchestrator prompt needs to handle failure cases explicitly — checking that all expected results were returned, retrying failed sub-agents, or degrading gracefully if some results are missing. This is one of the most important things to design for before deploying a split-and-merge workflow in production.

Can sub-agents use the same tools as the parent agent?

Yes. Sub-agents spawned via the Task tool have access to the full Claude Code toolset: reading and writing files, running shell commands, executing code, making web requests, and spawning their own sub-agents. The orchestrator can also restrict a sub-agent’s tool access by scoping its instructions carefully, though this is done through prompt-level guidance rather than hard permission controls.

---

Key Takeaways

• The split-and-merge pattern fans work out to up to 10 parallel sub-agents within a single Claude Code session, then merges results through an orchestrator
• Sub-agents are isolated — they only see what the orchestrator passes them, making the pattern predictable and debuggable
• Clear sub-agent instructions and a defined output schema are the two most important things to get right
• The pattern is best for parallelizable tasks with independent subtasks; sequential dependencies break the parallel benefit
• Start with 2–3 sub-agents to validate your orchestration logic before scaling to 10
• Tools like MindStudio can handle the integration and workflow layers that sub-agents need to call into, reducing the plumbing work in your orchestration logic

If you’re building multi-agent systems and want to skip the infrastructure layer, MindStudio is worth exploring — it takes about 15 minutes to build a first workflow, and the Agent Skills Plugin connects directly with Claude Code agents.