What a Claude Code subagent is
A Claude Code subagent is a separate Claude instance that your main session hands a single job. It spins up with its own fresh context window, does the work you described, and returns only the result. Think of your main session as a conductor and each subagent as a player: the conductor does not play every instrument, it assigns parts and listens for what comes back.
The detail that matters is the separate context window. When a subagent reads twenty files to answer one question, all of that reading happens in its window, not yours. Your main session never sees the twenty files, only the two-sentence answer. That keeps your own context clean and focused, which is the single biggest reason experienced builders reach for subagents.
The subagent triad: the three jobs they do well
Most good uses of a subagent fall into one of three jobs. We call this the subagent triad, and naming it makes the decision fast: before you spawn one, ask which of the three you are actually buying.
- Parallelize: run independent work at the same time. Three subagents can each research a different library, or audit a different folder, while you wait once instead of three times.
- Isolate: push a token-heavy job into its own window so it does not flood your main session. A subagent that greps a huge codebase returns the answer, not the thousand lines it read to find it.
- Specialize: hand a job to an instance you have pre-configured for exactly that task, with its own instructions and its own limited set of tools, so it behaves consistently every time.
If your task is none of those three, you probably do not need a subagent. A quick edit in a file you already have open is faster done directly. The triad is the filter.
How to spawn a subagent (the one-line version)
The simplest way to use a subagent is to ask for one in plain language. Inside Claude Code, say something like: use a subagent to find every place we call the old billing API and list the files. Claude launches a fresh instance, it does the search in its own window, and you get back a clean list without the search noise landing in your session.
To run work in parallel, ask for several at once: spin up three subagents, one to check the auth flow, one to check the payment flow, and one to check the email flow, and report what each found. They run together and each reports back. This is the everyday use, and it needs no setup at all.
How to create a custom subagent
When you find yourself describing the same kind of job over and over, turn it into a reusable subagent. A custom subagent is a markdown file in the .claude/agents folder of your project (or in your home folder to use it everywhere). The file is short: a few lines of frontmatter and then the instructions.
- name: a short identifier, for example test-runner or code-reviewer.
- description: one line on when this subagent should be used. Claude reads this to decide when to reach for it on its own.
- tools: the limited set of tools it is allowed to touch. A reviewer that can read but not write is safer and more predictable.
- model: which model it runs on, so you can route cheap jobs to a smaller model and hard jobs to a bigger one.
Below the frontmatter you write the system prompt: the role, the rules, and what good output looks like. Once saved, you can call it by name (use the code-reviewer subagent on this diff) and Claude can also invoke it automatically when a task matches the description. This is how a one-off becomes part of your standing workflow. If you are still deciding between subagents, skills, and other tools, our guide on [when to use skills, subagents, MCP, and hooks](/blog/claude-code-skills-subagents-mcp-hooks-when-to-use) lays out the decision.
What the June 2026 update changed
The June 2026 Claude Code release made subagents meaningfully more powerful, and it is worth knowing what is new before you design a workflow around them.
- Hierarchical subagents: a subagent can now spawn its own subagents, several levels deep. An orchestrator can break a large job into branches and let each branch fan out further on its own.
- Multi-repository sessions: subagents can operate across more than one local repository in a single session, which makes cross-project jobs like a synchronized dependency bump possible from one place.
- The agents view: the claude agents screen shows every session at once, including what is running, what is blocked waiting on you, and what is done.
- Cleaner permissions: background subagents now surface their permission prompts in your main session instead of silently denying them, so a job no longer stalls out of sight.
When not to use a subagent
Subagents are not free. Each one is a fresh instance with its own startup and its own token cost, and it cannot see your main conversation unless you put the context in the request. That makes them the wrong tool in three cases.
- Tightly dependent steps: if step two needs the exact output of step one, running them as separate parallel subagents just creates coordination overhead. Do sequential work in one place.
- Tiny tasks: spawning a subagent to rename a variable costs more time in setup than doing it yourself.
- Jobs that need your live context: if the work depends on the long discussion you have been having, a subagent that starts blank will miss it.
The honest rule is the triad in reverse: no parallel work, no context to isolate, and no repeatable specialty means no subagent. Reaching for one out of habit is how you slow yourself down while feeling productive.
A starter workflow you can copy this week
Here is a concrete loop to try on your next real task. It uses all three jobs of the triad and takes about ten minutes to set up the first time.
- Pick a job with independent parts, for example reviewing a pull request that touches three areas of the codebase.
- Ask your main session to spawn one subagent per area, each told to review only its area and return the top three issues it finds.
- Let them run in parallel while you keep working in your main session.
- When they report back, you have a clean, isolated summary from each, with none of the file-reading noise in your window.
- If one of those reviews is something you do every week, save it as a custom subagent in .claude/agents so next time it is one word away.
That is the whole idea: delegate the independent and the noisy work, keep your own context for the thinking. Once it clicks, you stop doing everything in one long thread and start running a small team. For the next step up, our walkthrough on [building your first AI agent with Claude Code](/blog/build-your-first-ai-agent-with-claude-code) shows how these same pieces assemble into a standing agent.
Learn this with us
Inside Claude Code Club we build subagent workflows like this in the open, share the custom agents that earn their keep, and help each other turn one-off prompts into repeatable systems. Start with the [curriculum](/curriculum) or join us at https://www.skool.com/claudecodeclub/about and bring the one task you most want to stop doing by hand.
Frequently asked questions
What is a subagent in Claude Code?
A subagent is a separate Claude instance that your main session hands a single job. It runs in its own fresh context window, completes the task, and returns only the result. Because its work happens in a separate window, it keeps your main session's context clean while it handles research, audits, or other focused jobs.
How do I create a custom subagent?
Create a markdown file in the .claude/agents folder of your project, or in your home folder to use it everywhere. Add frontmatter with a name, a one-line description of when to use it, the tools it is allowed to use, and the model it runs on. Below that, write its instructions. Once saved, you can call it by name and Claude can also invoke it automatically when a task matches the description.
When should I not use a subagent?
Skip a subagent when steps are tightly dependent on each other, when the task is tiny enough that setup costs more than doing it directly, or when the work depends on the live context of your current conversation. Subagents shine for parallel, noisy, or repeatable specialist work, not for quick sequential edits.
What changed for subagents in June 2026?
The June 2026 Claude Code update added hierarchical subagents that can spawn their own subagents several levels deep, multi-repository sessions that let subagents work across more than one local repo at once, an agents view that shows every running job on one screen, and cleaner permission handling so background subagents surface prompts in your main session instead of silently denying them.
Last reviewed by David Iya on June 30, 2026
