Claude Code Subagents Explained: Run Work in Parallel

If you have used Claude Code for a while, you have probably hit a wall where a single conversation tries to do too much at once. It reads files, runs tests, reviews code, and writes docs all in the same thread, and the context gets crowded. Claude Code subagents are the official answer to that problem. They let you hand a focused job to a separate helper that works in its own clean context and reports back.

This guide explains subagents in plain English. We will cover what they actually are, when they are worth the setup, how to create one, how the parallel execution works under the hood, and the limits you should know before you lean on them. No hype, no invented numbers. By the end, you will know whether subagents belong in your workflow or whether a simpler approach is fine.

What are Claude Code subagents?

A Claude Code subagent is a separate, specialized AI assistant that runs in its own context window, with its own system prompt and its own restricted set of tools, that the main session can delegate a focused task to.

Think of your main Claude Code session as a lead developer. When a job comes up that is self-contained, the lead does not do it personally. It hands the job to a teammate who only knows about that one task. That teammate is a subagent. It does the work, then returns a clean summary instead of dumping every file it read back into the main conversation.

This matters for two reasons. First, context stays clean. The main session does not get polluted with the hundreds of lines a subagent might read while hunting through a codebase. Second, focus improves. A subagent with a tight system prompt like “you are a test-runner that only runs and reports failing tests” behaves more predictably than one general assistant juggling everything.

Subagents are one of three ways Claude Code is extended. They are easy to confuse with the others, so it helps to separate them early. If you want the full breakdown, our guide on Claude skills vs MCP vs subagents walks through where each one fits. In short: Claude skills package reusable instructions, MCP connects external tools and data, and subagents delegate whole tasks to isolated workers.

When are subagents actually worth it?

Subagents pay off when a task is self-contained, repeats often, or would otherwise flood your main context — and they are overkill for quick one-off requests.

Not every job needs a subagent. If you just want Claude Code to rename a variable or explain one function, spinning up a separate worker adds friction for no benefit. Reach for subagents in these situations:

Repeated, well-scoped roles. A code reviewer, a test runner, a documentation writer, or a security checker that you call again and again. Defining it once as a subagent means consistent behavior every time.
Context-heavy exploration. When a task involves reading large parts of a codebase — for example, “find every place we call this deprecated API” — a subagent can do the digging and hand back only the answer, keeping your main thread lean.
Independent parallel work. When several jobs do not depend on each other, you can run them at the same time. More on that below.

A useful rule of thumb: if you find yourself pasting the same long instructions into Claude Code over and over, that is a signal the instructions belong in a subagent. The same instinct applies to Claude Code workflows in general — repeatable structure beats retyping.

Be honest about the cost, though. Each subagent runs its own model calls, so heavy parallel use burns through more tokens than a single thread. For a small task, the overhead is not worth it. Subagents shine on bigger, structured work, not on trivial edits.

How do you create a subagent?

You create a subagent either interactively with the /agents command inside a Claude Code session, or by hand as a Markdown file with YAML frontmatter in a .claude/agents/ folder.

The fastest way to get started is the interactive route. Inside a Claude Code session, run the /agents command. It walks you through naming the subagent, describing when it should be used, choosing which tools it can access, and writing its system prompt. This is the recommended path for your first subagent because it handles the file format for you.

If you prefer to write the file directly, a subagent is just a Markdown file. Project-level subagents live in .claude/agents/ inside your repository, and personal ones live in ~/.claude/agents/. The structure looks like this:

---
name: test-runner
description: Runs the test suite and reports only failures. Use after code changes.
tools: Bash, Read
---

You are a focused test-running assistant. Run the project's test
command, then report only the failing tests with their error
messages. Do not attempt fixes unless explicitly asked. Keep your
summary short.

The frontmatter has three important fields. The name identifies the subagent, the description tells the main session when to delegate to it, and the optional tools line restricts which tools it may use. Leaving tools out gives it access to the full set, which is rarely what you want — narrowing tools is part of what makes a subagent safe and predictable.

Once the file exists, Claude Code discovers it automatically. The main session reads the descriptions and routes matching work to the right subagent, or you can name one explicitly. Because project subagents live in your repo, they get version-controlled and shared with your team, just like any other config. If you are new to all this, our Claude Code tutorial and the install Claude Code guide cover the setup steps first. Always confirm field names against the official Claude Code docs, since the format can evolve.

How does parallel work happen?

Parallel execution happens when the main session delegates several independent subagent tasks at once instead of waiting for each one to finish — so multiple workers run side by side and report back together.

This is the feature that gets the most attention, and it is genuinely useful. Imagine you are building a feature that needs a backend endpoint, a frontend component, and a set of tests. Those three pieces do not depend on each other to get started. Instead of doing them one after another, you can ask Claude Code to fan out: spin up a subagent for each, let them work simultaneously, then gather the results.

The practical key is being explicit in your prompt. Vague requests like “parallelize this” tend to get ignored. Clear instructions work far better — for example, “Use three parallel subagents: one for the API route, one for the React component, and one for the tests. Each works independently, then report back.” Spelling out the number of workers and the exact scope of each prevents them from stepping on each other.

There are two phases worth naming. The fan-out is when the main session launches multiple subagents at once. The fan-in is when it waits for all of them to finish and then stitches their results into one coherent answer. Good parallel prompts make both phases obvious, so Claude Code knows when to spread out and when to pull back together.

This pattern is a small example of a larger idea. Coordinating several workers toward one goal is the core of multi-agent systems, and it connects to the broader shift toward agentic AI — software that plans and acts across steps rather than answering one prompt at a time.

What are the limits of subagents?

Subagents are powerful but bounded: they cannot share live state, they multiply token cost, they need genuinely independent tasks to run in parallel, and they add coordination overhead that can outweigh the benefit on small jobs.

The biggest practical limit is dependencies. Two subagents that need to read or write the same file, or that depend on each other’s output, cannot safely run at the same time. If a database migration must finish before the code that uses it, those are sequential steps, not parallel ones. Before fanning out, map out which tasks are truly independent. Forcing dependent work into parallel lanes leads to conflicts and confusing results.

The second limit is isolation cutting both ways. A subagent works in its own context, which is exactly why it stays clean — but it also means it does not automatically see what other subagents are doing. Communication happens through the main session, not directly between workers. For tightly coupled work where everyone needs the same evolving picture, a single thread is often simpler.

The third is cost and overhead. Every subagent is a separate run of the model with its own context, so heavy parallel use consumes more tokens and can run into your plan’s usage limits faster. There is also a coordination tax: setting up, dispatching, and merging results takes effort that only pays off on substantial work. For a one-line fix, skip the machinery.

Finally, subagents are not a magic fix for unclear instructions. A poorly scoped subagent produces poorly scoped output, just in parallel. If you are still finding your footing, building solid habits with the Claude Code guide first will make subagents far more useful. They amplify a good workflow; they do not create one.

FAQ

What is the difference between a subagent and a skill in Claude Code?

A skill packages reusable instructions and resources that extend what Claude Code knows how to do, loaded into the current session when relevant. A subagent is a separate worker with its own isolated context that you delegate a whole task to. Skills make the main assistant smarter; subagents offload work to a teammate. See our Claude skills vs MCP vs subagents breakdown for the full comparison.

Can Claude Code run subagents in parallel?

Yes. When the main session delegates several independent tasks at once instead of waiting for each to finish, the subagents run side by side. The trick is to be explicit in your prompt about how many workers you want and what each one should focus on. Tasks that depend on each other still have to run in order.

Where are Claude Code subagents stored?

Project-level subagents live in a .claude/agents/ folder inside your repository, so they are version-controlled and shared with your team. Personal subagents live in ~/.claude/agents/ in your home directory. Each one is a Markdown file with YAML frontmatter. Check the official docs for the exact, current format.

Do subagents cost more tokens?

Yes, they generally do. Each subagent runs as its own model session with its own context, so delegating and running several in parallel consumes more tokens than handling everything in one thread. That overhead is worth it for large, well-structured tasks but not for quick one-off edits, where a single conversation is more efficient.

How many subagents can run at once?

Claude Code limits how many subagents run simultaneously, queuing additional ones as slots free up. The exact number can change between versions, so do not hard-code an assumption — consult the official Claude Code docs for current behavior. In practice, you rarely need many at once; a handful of well-scoped workers covers most real tasks.

Conclusion

Subagents turn Claude Code from a single busy assistant into a small, coordinated team. The core idea is delegation with isolation: hand a focused job to a worker that runs in its own clean context, then get back a tidy summary instead of a flood of detail. When several jobs are truly independent, you can run them in parallel and finish faster.

The honest takeaway is that subagents are a tool for structured, repeatable, or context-heavy work — not a default for everything. Use the /agents command to define your first one, keep each subagent narrowly scoped with the tools it actually needs, and map dependencies before you fan out. Start small with a single reviewer or test-runner subagent, see how it fits your routine, and grow from there. Paired with a clear understanding of agentic AI and a solid base from the Claude Code guide, subagents become one of the most practical ways to get more done with less mess.