Claude Code Subagents: How to Run Parallel AI Workflows (2026)

Quick Answer: Subagents in Claude Code are independent Claude instances that your main agent spawns to handle subtasks in parallel. Instead of one agent working sequentially, the main agent delegates to subagents that each focus on one job and report back. Use the /batch command or ask Claude to parallelize tasks explicitly. Subagents can cut complex task completion time by 50-70%.

What are Claude Code subagents?

When you ask Claude Code to "refactor this module, write tests, and update the docs," a single agent does everything one step at a time. With subagents, the main agent breaks the task into parts and spawns separate Claude instances to handle each one simultaneously.

Each subagent gets its own context window, runs independently, and returns results to the main agent. The main agent combines everything into a final output. Because subagents work in parallel, complex multi-step workflows finish significantly faster.

Think of it like a tech lead delegating to team members. The lead understands the big picture, splits the work, assigns each piece to a specialist, reviews their output, and assembles the final result.

See SKILL.md in action

Doxaflow

by Matthew Ward

$19

finalize

by Alex Shi

$5

Flutter Cross Master

by Pietro Giovanni Vaccarello

$7

Browse all skills

How do subagents work in Claude Code?

Claude Code handles subagent orchestration through two mechanisms:

The /batch command. This is the built-in way to run parallel work. Give it a natural language instruction and Claude splits it across multiple agents automatically. Each agent handles a subset of files or tasks.

/batch Add error handling to all API endpoints in src/routes/

Claude analyzes the scope, identifies which files need changes, divides the work across subagents, and each subagent handles its assigned files independently. Results are merged back together.

Explicit delegation. You can ask Claude to use subagents directly:

Break this into parallel tasks:
1. One agent refactors the auth module to use JWT
2. One agent writes tests for the refactored auth
3. One agent updates the API docs
Start all three at once.

Claude creates three independent sessions, each working on its assigned task with only the context it needs.

When should I use subagents vs a single agent?

Use subagents when the task has naturally independent parts. Three modules that each need tests? Three subagents, each writing tests for one module. A codebase-wide refactor touching 40 files? Subagents split the files and work in parallel.

Use a single agent when steps depend on each other. If step 2 needs the output of step 1, you can't parallelize. A single agent handling the sequential chain is better.

Good subagent use cases:

• Parallel test generation across independent modules
• Codebase-wide style changes or migrations
• Multi-file refactoring where files don't depend on each other
• Research tasks: "investigate how competitors handle auth, rate limiting, and caching"
• Code review with multiple perspectives: security reviewer, performance reviewer, style reviewer

Better as a single agent:

• Building a feature from scratch where each file depends on the previous one
• Debugging a specific issue that requires tracing through connected code
• Sequential workflows where context from early steps informs later ones

How do subagents handle context and file access?

Each subagent gets a scoped context. The main agent decides what each subagent needs to know and passes only that information. A subagent writing tests for the auth module gets the auth module code, the existing test patterns, and the testing framework config. It doesn't get the entire codebase.

This scoping is actually an advantage. A single agent working on a large codebase might run into context window limits. Subagents each get a focused slice, which means they can go deeper on their specific task.

Subagents have full file system access within your project. They can read files they need, write their output, and run commands. The main agent coordinates to prevent conflicts, like two subagents trying to modify the same file.

How does /simplify use subagents?

The /simplify command is one of the best examples of subagents in practice. When you run it after finishing a feature or fix, Claude spawns three parallel review agents:

1. One checks for code reuse opportunities
2. One checks code quality and potential issues
3. One looks for simplification opportunities

Each reviewer examines the code independently, then their findings are merged into a single report. This multi-perspective approach catches things a single review pass would miss.

Can I combine subagents with skills?

Yes. Each subagent can use the skills installed in your project. If you have a code review skill installed, a subagent assigned to review code will use that skill's instructions. If you have a testing skill, a subagent writing tests follows those patterns.

This means you can set up specialized subagent workflows. A "review" subagent uses your code review skill, a "test" subagent uses your testing skill, and a "docs" subagent uses your documentation skill. Each subagent gets both the task context and the relevant skill instructions.

For skills that work well with subagent workflows, check the Testing and QA and Code Review categories on Agensi.

What are the limitations of subagents?

Token cost. Each subagent is an independent Claude session. Running 5 subagents in parallel uses roughly 5x the tokens of a single agent. For simple tasks, the overhead isn't worth it.

Coordination overhead. The main agent needs time to plan the split, scope each subagent, and merge results. For tasks that take under a minute with a single agent, adding subagents makes it slower, not faster.

Merge conflicts. If two subagents modify related code (like a function and its callers), the main agent has to resolve conflicts when merging. This usually works fine but can occasionally require manual intervention.

No cross-subagent communication. Subagents can't talk to each other during execution. They each work independently and only communicate through the main agent when they're done. If subagent A discovers something subagent B needs to know, that information doesn't flow until both finish.

How do subagents compare to MCP-based multi-agent systems?

Subagents in Claude Code are built-in and handle parallel task execution within a single coding session. They're all Claude instances working on your codebase.

MCP-based orchestration is different. Tools like the Agensi MCP server let agents discover and load external capabilities. An agent connected to multiple MCP servers can pull in skills, search databases, and interact with APIs all within one conversation.

The two approaches complement each other. Subagents parallelize the work. MCP connections expand what each agent can do. A subagent reviewing code could use an MCP server to check security advisories, while another subagent writing tests uses an MCP server to look up the testing framework docs.

---