What exactly is a subagent in Claude Code?

It's an independent Claude session that the main agent launches to solve a specific task. It has its own context (it doesn't inherit your conversation) and, when it finishes, returns a single result message to the agent that launched it. It's for delegating heavy work—researching many files, running a long task—without flooding your main conversation with all the intermediate steps.

How is a subagent different from just continuing in the same session?

In the same session, everything Claude reads and writes stays in the context and competes for the model's attention. A subagent isolates that work: it does the dirty work off to the side and brings you back only the distilled answer. You gain two things: a clean context in your main conversation and the ability to launch several subagents at once for work that doesn't depend on each other.

How do I launch several subagents in parallel?

By asking, in a single message, for the tasks to be split across independent agents. Claude dispatches them all at once and waits for all of them to finish before synthesizing. The key is that the tasks be genuinely independent: if one's result feeds the next, no parallelism is possible and it's better to run them in sequence.

When should you NOT use a subagent?

When the task is small (you'd do it faster than explaining it), when there are chained dependencies (B needs A's output), when it requires back-and-forth with you partway through, or when you already know exactly which file and which piece of data you need. Delegating has a fixed cost in context and startup; below a certain size it's not worth it.

Can a subagent modify my files or only research?

It depends on the type. There are read-only subagents, designed to research and return findings without touching anything, and there are ones with full permissions to execute changes. To sweep the codebase looking for something, use a read-only one; to isolate a long writing task, use one with permissions, ideally on its own branch or worktree if your setup allows it.

Subagents in Claude Code: Parallel Work Without Cluttering Your Context

There comes a point where Claude Code starts to feel cramped within a single conversation. You ask it to review half a dozen files to find something, and the session fills up with code dumps you no longer need. Or you want it to research three things at once and end up doing them one after another, waiting. The tool to break through that ceiling is called a subagent, and most people don't use it because they don't understand when it helps and when it gets in the way.

This guide is for exactly that: understanding what a subagent really is, how to parallelize work, how to write the request so it comes back with something useful, and—just as important—when NOT to touch it.

Note

A subagent is a Claude session inside your Claude session. The main agent launches a child with its own context, gives it a task, and the child works on its own and returns a single message with the conclusion. The entire intermediate process stays in the child, not in your conversation.

What a subagent is (and why it's not "opening another tab")

The temptation is to think of a subagent as a second chat window. It isn't. The key difference is context: the subagent starts clean, doesn't see your conversation, does its work, and returns a distilled answer. It doesn't bring you the 40 files it read; it brings you the sentence that sums up what it found.

That changes the mental model. In a normal session, everything Claude reads stays there taking up space and competing for its attention. The more noise you pile up, the worse it reasons about what matters. The subagent is the way to do the dirty work outside and keep only the answer.

There are different types depending on permissions: the read-only ones, designed to research and search without touching anything, and those with full permissions to execute changes. Pick the most restrictive one that does the job: to find where a function is defined, a read-only one; to isolate a long refactor, one with permissions.

What they're for: the three uses worth your time

Not everything should be delegated. These are the three scenarios where a subagent wins hands down:

Researching without cluttering the context. "Find which files use this pattern and tell me which ones need touching." The subagent reads 30 files and returns a list of 5. Your conversation never sees the sweep, only the result.
Parallelizing independent work. Three questions that don't depend on each other get launched at once and come back together. This is what truly multiplies: it's not that Claude works faster, it's that it works on three fronts simultaneously.
Isolating a long, autonomous task. A migration, a test sweep, a massive translation. Something with a clear goal that doesn't need supervision partway through and produces a finished deliverable.

The common thread across all three: tasks with a sharp goal and a clear endpoint. If you can't describe when the subagent is "done," it's probably not a candidate for delegation.

How to launch them: in series and in parallel

To launch a subagent, you describe the task to the main agent and ask it to delegate. The piece almost no one takes advantage of is parallelism: if you request several independent tasks in a single message, Claude splits them across subagents that run at the same time and waits for all of them to finish before synthesizing.

Three subagents in parallel

I need three independent investigations. Launch them IN PARALLEL (one subagent each) and then bring it all together:

1. Where and how the newsletter form is validated in this repo (files + function).
2. Which email provider is currently wired in and where the API key is configured.
3. Whether there are tests covering subscriber sign-up, and which ones.

Each subagent returns only: absolute file paths + 2-3 lines of conclusion. No dumping entire code.

Notice two details in the request. First, "IN PARALLEL": you're making it clear that the three are independent and can run together. Second, the output format ("paths + 2-3 lines, no dumping code"): without this, each subagent hands you back a wall of text and you lose the advantage of a clean context.

The flip side: when a task depends on the result of another (B needs what A produced), no parallelism is possible. That runs in sequence—in the same conversation or with sequential subagents, not at once.

Best practices: the request is everything

A subagent is only as good as its brief. Since it can't see your conversation, anything you don't tell it, it doesn't know. Three rules:

Goal, scope, and output format, explicit. What you want, how far it can go, and how it hands it back to you. "Find X" is vague; "find X in src/, ignore tests, give me absolute paths and one line per finding" is actionable.
Ask for the distillate, not the process. The value of a subagent is that it filters. If you let it return everything it read, you've traded one dirty context for another. Demand a conclusion, not a transcript.
One task, one subagent. The same principle that governs a healthy session: one goal per agent. If you cram three unrelated topics into a single request, the subagent will do them half-baked.

Tip

If you're going to launch a writing subagent on a long task, give it its own isolated space (a Git branch, or a worktree if your workflow supports it). That way it works without stepping on what you have half-finished, and you review the result all at once instead of watching changes appear live.

And a golden rule for research: don't duplicate the work. If you delegated a search to a subagent, don't also do it yourself "just in case" while you wait. Wait for the result. The classic mistake is launching the subagent and then, impatient, reading the same files yourself: you pull the same thread twice.

When NOT to use subagents

This section matters as much as the previous ones, because overusing subagents is as common as underusing them. Don't use them when:

The task is small. If you'd do it faster than explaining it, explaining it is a waste of time. Delegating has a fixed startup-and-context cost; below a certain size, it's not worth it.
There are chained dependencies. If step B needs A's output, there's nothing to parallelize. Forcing it only adds friction.
It needs back-and-forth with you. The subagent works in one go and returns a single response. If the task requires you to make decisions partway through, keep it in the main conversation where you can step in.
You already know the exact file and data point. To look at ONE value in ONE file you've already located, opening it is instant. Sending a subagent to find what you already know the location of is bureaucracy.

The summary rule: delegate when the work is large, independent, and clearly defined; do it yourself when it's small, dependent, or open-ended exploration.

The mental model that changes everything

Stop thinking of Claude Code as "an assistant" and start thinking of it as "an assistant that can hire others." You direct; the subagents work parallel fronts and bring you reports. Your job stops being to do, and becomes to delegate and synthesize.

Once you internalize that, the question on every task changes. It's no longer "how do I do this?" but "do I do this myself or delegate it, and if I delegate, what does it need to know to come back with something useful?" That second question—goal, scope, output format—is what separates the people who use subagents to truly speed up from those who only add noise. Start with a single well-written delegation: a research request, with its output format spelled out. When you see the clean distillate come back instead of the wall of text, you won't want to work any other way.