What Claude Code Subagents Are
Claude Code subagents are extra agents you spin up from inside your main session to handle a piece of work on their own. Think of your main Claude Code session as the lead on a project. A subagent is a teammate you hand a specific job to - go read every file that touches billing, or go write and run the tests for this module - while you keep your attention on the bigger thread. The subagent does the job, then hands you back a tidy summary instead of a pile of raw output.
The part that makes them powerful is that each subagent runs in its own clean context. It does not carry the clutter of your main conversation, and its own messy exploration never lands back in yours. It goes off, works in a separate space, and returns only the result. That single design choice is what lets you run several of them at once and keep your main session clear and fast.
- Its own context window, separate from your main session, so nothing bleeds across.
- A type or role - a general-purpose worker, an explorer for searching the codebase, a planner, or a custom agent you define yourself.
- A single task you describe when you launch it, since it starts fresh every time with no memory of your chat.
- A summarized result it returns to your main session when it finishes, not the full transcript of everything it did.
Why Run More Than One Agent at Once
A single agent working through a big task in one context has two limits. It can only do one thing at a time, and everything it looks at piles into the same conversation, which slowly crowds out the thread you actually care about. Subagents solve both. They let independent work happen in parallel, and they keep heavy, noisy work out of your main context so your lead agent stays sharp on the real goal.
Main session vs subagent - which does what
| Dimension | Your main session | A subagent |
|---|---|---|
| Role | Holds the plan and the thread that matters | Does one focused, self-contained job |
| Context | Everything you and it have discussed | A clean slate, briefed fresh each time |
| Best for | Decisions, direction, tying results together | Searching, testing, research, repetitive digging |
| What you get back | The running conversation | A short summary of the result |
The Two Jobs Subagents Are Best At
The first job is parallelizing independent work. If you have three questions that do not depend on each other - where is the auth logic, how does the payment flow work, and what does the deploy script do - you can launch three explorers at once and get three answers back together instead of waiting through them one at a time. Anything that can be split into pieces that do not need each other is a natural fit for running several agents in parallel.
The second job is protecting your context. Some tasks generate a mountain of output - reading a huge folder, scanning logs, combing through search results. If all of that lands in your main session, it crowds out the thread you are trying to hold onto. Hand that work to a subagent and only the conclusion comes back. Your lead agent never has to wade through the raw pile, so it stays focused and responsive on the part that needs your judgment.
How to Launch a Subagent
You do not need any special setup to start. In plain English, tell Claude Code to use a subagent for a chunk of work and describe the job. It picks the right kind of agent, hands over the task, and reports back. As you get comfortable, you can be explicit about what you want.
- Decide what to hand off - pick work that is either independent or noisy, the two cases where a subagent pays off.
- Choose the kind of agent - a general-purpose one for open-ended tasks, an explorer for searching the codebase, a planner for designing an approach.
- Describe the task in full, because the subagent starts fresh and knows nothing about your conversation.
- Say whether to wait for it or let it run in the background while you keep working.
- Read the summary it returns and fold the result into your main thread.
How to Brief a Subagent So It Actually Delivers
The most common reason a subagent disappoints is a thin brief. Because it starts with a blank slate, it has none of the context you have built up in your main session. It has not seen what you tried, what you ruled out, or why the task matters. So brief it like a sharp colleague who just walked into the room - give it enough to make good judgment calls instead of guessing.
- State the goal and why it matters, not just the narrow instruction, so the agent can make sensible calls on its own.
- Include the specifics it cannot see - file paths, names, what you already checked, what a good answer looks like.
- Say clearly whether you want research and findings or actual code changes, since it cannot read your intent.
- Tell it how much detail you want back - a two-line answer or a full breakdown - so the summary is useful.
Foreground or Background: When to Wait
You can run a subagent in the foreground, where you wait for its result before moving on, or in the background, where it works while you carry on and notifies you when it is done. The rule is simple. If you need the answer before you can take the next step - a research agent whose findings decide your next move - run it in the foreground. If the work is genuinely separate and you have other things to do meanwhile, send it to the background and keep building. Do not sit and poll a background agent; the whole point is that you get on with something else.
A Simple Rule for When to Use Subagents
Do not reach for a subagent out of habit. For one quick lookup or a small edit, launching a separate agent is more overhead than it is worth - just do it in your main session. Subagents earn their keep when work is parallel or heavy. If you can split a task into independent pieces, or if a task would dump a mountain of output into your chat, that is the moment to delegate it.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
What is a subagent in Claude Code?
It is a separate agent you launch from your main session to handle one focused task - like searching the codebase, running tests, or doing research. It runs in its own clean context and hands back a short summary of the result instead of dumping everything into your main conversation.
When should I use a subagent instead of just asking Claude Code directly?
Use one when work is either independent (so several agents can run in parallel) or noisy (so heavy output would clutter your main chat). For a single quick lookup or a small edit, skip the subagent - launching one is more overhead than it saves.
Can Claude Code run multiple subagents at the same time?
Yes. If you have several tasks that do not depend on each other, Claude Code can launch them in parallel and return the results together. The trick is to ask for all of them in one go - asking one at a time forces the agents to run in sequence and you lose the speed-up.
Do subagents remember my main conversation?
No. Each subagent starts fresh with a blank slate, which is exactly why they keep your context clean. It also means you have to brief them fully - include the goal, the relevant file paths, what you already tried, and what a good answer looks like, because they cannot see any of it otherwise.
What is the difference between running a subagent in the foreground and the background?
In the foreground you wait for the result before continuing, which is right when the answer decides your next step. In the background the agent works while you carry on with other things and notifies you when it finishes. Use the background for genuinely separate work, and do not sit polling it.
Are subagents only useful for large projects?
No, but the payoff grows with size. Even on a small project they help when a task would flood your chat with output or when you have a few independent questions to answer at once. On larger projects, delegating exploration and testing to subagents is what keeps your main session fast and focused.
Last reviewed by David Iya on July 16, 2026
