Claude Code Subagents: Parallel Work Explained

TL;DR

• Claude Code subagents are separate Claude sessions your main agent spawns to run tasks in parallel.
• They speed up work because multiple tasks run at the same time instead of one after another.
• Each subagent runs in a sandbox. File writes from subagents do not persist. The parent session writes the files.
• Use subagents when tasks are independent. Do not spawn them for steps that depend on each other.
• The orchestrator pattern (one controller, many workers) is how you build real multi-agent systems in Claude Code.

---

I run Claude Code subagents every single day at Devwiz. They are one of the main reasons my output has jumped so much over the past year. If you are not using them yet, this post explains what they are, when to use them, and how to set them up properly.

What are Claude Code subagents?

A subagent is a separate Claude Code session that your main agent (the orchestrator) spawns to do a piece of work.

Think of it like this. You are the manager. You have a team. Instead of doing every task yourself, you hand work out to team members and let them run in parallel.

In Claude Code, the orchestrator is your main session. Subagents are the workers. The orchestrator gives each worker a task, they run at the same time, and results come back to the orchestrator.

This is different from a single Claude session doing tasks in sequence. Sequential work means task one finishes, then task two starts, then task three. Parallel work means all three run at the same time.

Parallel agents do not just save time. They change what is possible in a single session.

Want to see how this fits into a full Claude Code workflow? Start with the Claude Code complete guide for the full picture.

How do subagents actually work?

Each subagent is a fresh Claude Code session. It gets a prompt from the orchestrator. It does its work. It returns output as text.

Here is the important bit. Subagents run in a sandbox. Any file a subagent writes does not persist back to your main session. This catches a lot of people out.

The correct pattern is:

1. Orchestrator spawns subagents with clear task prompts.
2. Subagents do their work and return text output.
3. Orchestrator reads that text output.
4. Orchestrator writes the files itself.

If you expect subagents to write files directly into your project, it will not work. The parent session must do the writing. Get that pattern right early and you will avoid a lot of confusion.

When should you use subagents?

Use subagents when your tasks are independent of each other.

Good candidates:

• Researching three different topics at the same time.
• Drafting five blog posts in parallel.
• Running quality checks on multiple files simultaneously.
• Generating copy variations for different audiences at once.
• Analysing several data sources that do not depend on each other.

Bad candidates:

• Step one generates a plan, step two executes the plan. These are sequential. Step two cannot start until step one is done.
• Task A needs the output of task B. These are dependent. Run them in order.

The rule is simple. If task B needs the result of task A to start, run them in sequence. If they can run without knowing what the other is doing, run them in parallel.

What does the orchestrator pattern look like?

The orchestrator pattern is the standard way to build with subagents.

You have one main Claude Code session. Its only job is to coordinate. It does not do the detailed work itself. It breaks the work into pieces, assigns each piece to a subagent, waits for results, then assembles the output.

A real example from my work at Devwiz. I need to produce a content pack for a client. That pack includes a LinkedIn post, a blog intro, three email subject lines, and a summary doc.

Without subagents, I run each one in sequence. Five tasks, each waiting for the previous to finish. With subagents, the orchestrator assigns all five tasks at once. All five run in parallel. I get all five results back at the same time. The orchestrator assembles them into the final pack and writes the files.

The wall-clock time drops dramatically. The quality stays the same or improves because each subagent has full context for its specific task.

The orchestrator does not do the work. It manages the work. That shift is everything.

If you are building team workflows with Claude Code, the Claude Code for teams post covers how to structure this across multiple contributors.

How fast is the speedup?

It depends on how many tasks you are running and how long each one takes.

If you have five tasks that each take two minutes, sequential execution takes ten minutes. Parallel execution takes about two minutes. That is a five-times speedup on that batch.

In practice, the speedup is real but not always that clean. Some tasks are longer than others. The orchestrator has its own overhead. But across a full working day, the difference is significant.

At The Orchestrators, we see teams get three to five times more output when they shift from sequential AI use to proper orchestrated parallel workflows. That is not a theoretical number. It is what shows up in real client work.

What about MCP and tool access in subagents?

Subagents can use tools, including MCP servers, if they are configured in the session.

Read the Claude Code MCP post for the full breakdown of how MCP works. The short version: MCP gives Claude Code access to external tools and data sources. Subagents can use those same tools if the orchestrator passes them through correctly.

One thing to watch. Subagents that call external APIs or write to external services do have real-world effects. Those are not sandboxed. Only file writes to the local project are the ones that do not persist. If a subagent calls an API or sends a message, that happens for real. Set clear boundaries in your subagent prompts. Tell each agent exactly what it is allowed to do and what it should return.

Common mistakes people make

Expecting subagents to write files. The file write does not persist. The orchestrator writes the files. Always.

Spawning subagents for dependent tasks. If task B needs task A's output, run them in order. Parallelising dependent tasks breaks everything.

Vague subagent prompts. Each subagent gets a fresh context. It does not know what the other subagents are doing. Give it a complete, specific prompt.

Not validating output before writing. The orchestrator should check what comes back before writing files. Garbage in, garbage out. Validate first.

Running too many subagents at once. There is a limit to how many can run simultaneously. Start with a small number. Test. Scale up once the pattern works.

Agentic AI for business is bigger than just Claude Code. See the agentic AI for business post for how orchestration fits into a broader AI strategy.

How do I get started?

If you are new to subagents, here is the simplest path:

1. Pick a task you do repeatedly that has multiple independent parts.
2. Write a clear prompt for each part.
3. Set up an orchestrator session that spawns a subagent for each part.
4. Collect the text output from each subagent.
5. Have the orchestrator write the assembled result to a file.

Run it. Check the output. Refine the prompts. Then scale the pattern to more complex work. The first time it clicks, you will understand why this changes how AI-assisted work feels.

---

Related reading

• Claude agents and subagents: orchestrate like a conductor the bigger picture.
• Skills vs Projects vs Subagents vs MCP one decision tree for which to use.

---

FAQ

What is a Claude Code subagent?
A subagent is a separate Claude Code session spawned by an orchestrator (your main session) to handle a specific task. It runs in parallel with other subagents, returns text output to the orchestrator, and does not persist file writes back to the main project.

Can subagents write files to my project?
No. File writes from subagents are sandboxed and do not persist. The parent orchestrator session must read the subagent output and write the files itself. This is a common gotcha. Get this pattern right early.

How many subagents can I run at once?
There is a limit, and it varies. Start small, test the pattern with two or three subagents, then scale up. Running too many at once can cause failures. Build the habit of validating before scaling.

When should I use subagents instead of a single session?
Use subagents when you have multiple independent tasks that do not depend on each other. If your tasks are sequential, run them in order in a single session. Parallel only makes sense for independent work.

---

If you want to build a proper orchestrated AI system in your business, not just use Claude Code for one-off tasks, let's talk. Book a free AI transformation call and we will map out where parallel agents can have the biggest impact on your workflow.