Claude Code Subagents: How They Work and When to Use Them
September 30, 2026
Claude Code subagents are separate workers that Claude hands a side task to. Each one runs in its own context window, with its own system prompt, its own tool list, and its own permissions. It does the messy part, like reading forty files or running the whole test suite, and sends back only a summary.
Your main conversation stays about the thing you're building, not the log output it took to find one failing test.
Here's how subagents compare with the features people mix them up with, as of September 2026:
| Feature | Where the work happens | What comes back to you | Best for |
|---|---|---|---|
| Subagent | A fresh context window inside your session | A summary | Noisy side tasks, restricted tools, specialized workers |
| Skill | Your main conversation (unless forked) | The work itself, in your context | Reusable instructions and workflows |
| Agent team | Several full Claude Code sessions | Findings the teammates share and argue over | Parallel work where workers need to talk to each other |
| Background session | A separate session you dispatch | Whatever that session produces | Independent tasks you hand off and check later |
The rest of this guide covers what a subagent actually receives, the built-in ones, where custom definition files live, how Claude decides to use one, and when you're better off without one.
What a Claude Code subagent actually is
Anthropic's subagents documentation puts the rule of thumb plainly: use one when a side task would flood your conversation with search results, logs, or file contents you won't look at again.
The important detail is what a subagent doesn't see. It starts fresh. Your conversation history, the files Claude already read, and the skills you already invoked stay behind. Claude writes a delegation message summarizing the task, and the subagent works from that.
A standard subagent starts with:
- Its own system prompt. The Markdown body of its definition file, plus basic environment details like the working directory. It does not get the full Claude Code system prompt.
- The task message Claude wrote when it delegated.
- Your CLAUDE.md files, at every level the main conversation loads. If you're still setting yours up, our CLAUDE.md guide covers what belongs in it.
- A git status snapshot, when you're in a repository.
- Any skills named in its
skillsfield, loaded in full.
Two things never reach it: your output style and your auto memory. A subagent can have its own persistent memory directory instead, through the memory field.
That's why rules go missing. A rule you only typed earlier in the chat never reached the subagent. Restate it, or put it in CLAUDE.md.
One cost note. A subagent sends its own requests, and the docs say they count toward the same usage limits as your main conversation. Five subagents researching in parallel means five streams of work, not one.
The built-in subagents
You don't have to write anything to start using subagents. Claude Code ships with several, and Claude reaches for them on its own:
| Built-in | Tools or model | What Claude uses it for |
|---|---|---|
| Explore | Read-only (Write and Edit denied) | Searching and understanding a codebase without changing it |
| Plan | Read-only | Gathering context during plan mode before presenting a plan |
| General-purpose | Every tool available to subagents | Multi-step tasks that need both exploring and editing |
| claude-code-guide | Runs on Haiku | Answering your questions about Claude Code itself |
| statusline-setup | Runs on Sonnet | Configuring your status line via /statusline |
Explore and Plan are tuned to be fast and cheap. They skip your CLAUDE.md files and the git status snapshot. When Claude calls Explore, it also picks a thoroughness level: quick, medium, or very thorough.
They're also one-shot: they return no agent ID, so Claude can't resume them. Research you'll want to continue belongs to general-purpose or a custom subagent.
Where Claude Code subagents live: the agents folder
A custom subagent is a single Markdown file with YAML frontmatter. Where you save it decides who gets it:
| Location | Scope | Priority when names clash |
|---|---|---|
| Managed settings | Your whole organization | 1 (highest) |
--agents CLI flag (JSON) | The current session only | 2 |
.claude/agents/ | The current project | 3 |
~/.claude/agents/ | All your projects | 4 |
A plugin's agents/ directory | Wherever the plugin is enabled | 5 (lowest) |
Project subagents are the ones to commit, so everyone on the repo gets the same reviewer and test runner. User subagents in ~/.claude/agents/ follow you into every project.
Some specifics that trip people up:
- Subfolders are fine. Both folders are scanned recursively, so
agents/review/works. The folder path doesn't matter; identity comes only from thenamefield. - Duplicate names are a coin toss. If two files in the same tree share a
name, only one loads, and the docs say the choice follows filesystem read order. Keep names unique. - Edits apply live. Claude Code watches both folders and picks up changes within seconds. The exception: if the
agentsfolder didn't exist when the session started, restart once. - Plugin agents are restricted. For security, plugin subagents ignore the
hooks,mcpServers, andpermissionModefields. Copy the file into.claude/agents/if you need them. Our Claude Code plugins guide covers how plugins package agents.
Writing a subagent definition file
Here's a small, illustrative example. Save it as .claude/agents/test-runner.md:
---
name: test-runner
description: Runs the test suite and reports only failing tests. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: haiku
---
You run tests and report failures. Run the project's test command,
then list each failing test with its file and the first error line.
Do not fix anything. Do not paste passing output.
Only name and description are required. Everything after the closing --- becomes the subagent's system prompt.
The frontmatter fields you'll use most:
| Field | What it does |
|---|---|
tools | Allowlist of tools. Leave it out and the subagent inherits every tool available to subagents |
disallowedTools | Denylist, removed from the inherited or listed set |
model | sonnet, opus, haiku, fable, a full model ID, or inherit |
permissionMode | The permission mode it runs in, such as plan or acceptEdits |
skills | Skills preloaded into its context at startup |
mcpServers | MCP servers only this subagent can reach |
hooks | Hooks that run only while this subagent is active |
memory | A persistent memory folder: user, project, or local scope |
isolation | Set to worktree to give it its own git worktree |
maxTurns | A cap on agentic turns before it stops |
Field names are camelCase, and Claude Code silently ignores a field it doesn't recognize. Write max_turns and nothing happens. A file with no description, or YAML that doesn't parse, is skipped without a message too. Run with --debug to see why.
How do you create one? Ask Claude to write the file, or write it yourself. As of v2.1.198, the /agents command no longer opens the old creation wizard. It prints a reminder to do one of those two things instead. Older tutorials that walk through the wizard are out of date.
How Claude picks a subagent
Automatically. Claude reads your request, the current context, and every subagent's description, and delegates when one matches. That makes the description the most important line in the file. Say when to use it, not just what it is. Adding "use proactively" nudges Claude to delegate without being asked.
Keep descriptions short, too. All of them load into context. When your custom subagents' descriptions together pass 15,000 tokens, Claude Code shows a warning at startup. Put detail in the system prompt, which only loads when the subagent runs.
Explicitly, in three escalating ways:
- Name it in your prompt. "Use the test-runner subagent on the payments module." Claude usually delegates, but it still decides.
- @-mention it. Pick it from the
@typeahead, or type@agent-test-runner. This guarantees that subagent runs for the task. - Run the whole session as it.
claude --agent test-runnermakes the main thread take on that subagent's prompt, tools, and model. Set"agent"in.claude/settings.jsonto make it the project default.
In an interactive session, subagents usually run in the background, so you keep working while they do. Background subagents get a slightly smaller built-in tool set, and any permission prompt they hit surfaces in your main session with the subagent's name on it.
Subagents can spawn their own, up to three layers deep by default, with up to 20 running at once.
Subagents vs skills vs agent teams
These overlap enough to confuse people. Anthropic's feature overview draws the lines:
| Subagent | Skill | Agent team | |
|---|---|---|---|
| What it is | An isolated worker | Reusable instructions or a workflow | Several coordinated Claude Code sessions |
| Context | Its own window; only a summary returns | Adds to your main window | Each teammate has its own window |
| Communication | Reports back to whoever spawned it | None, it's content | Teammates message each other directly |
| Availability | On by default | On by default | Experimental, disabled by default |
| Token cost | Lower than a team, since only a summary returns | Description loads each session, full content only when used | Higher, since each teammate is a separate Claude instance |
Skills are content. A skill is a SKILL.md that teaches Claude a task, and by default it runs in your conversation. The two combine in both directions: a subagent can preload skills through skills:, and a skill with context: fork runs inside a subagent. Our Claude Skills guide covers the format.
Agent teams are the heavier tool. A lead session spawns teammates that share a task list and challenge each other's findings. Turn them on with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Anthropic's own advice is to check whether subagents do the job first.
Background sessions are different again. Agent view, opened with claude agents, dispatches full sessions that run without a terminal attached. It's in research preview. Use it when you're handing off independent jobs, not delegating a side task inside one conversation.
Hooks sit alongside all of this. SubagentStart and SubagentStop fire when a subagent begins and ends, and tool hooks in settings.json fire inside subagents too. You can also scope hooks to one subagent in its frontmatter. The Claude Code hooks guide walks through the events.
When to use subagents, and when not to
The docs give a clean split.
| Use a subagent when | Stay in the main conversation when |
|---|---|
| The task produces verbose output you won't need again | The task needs back-and-forth or iterative refinement |
| You want to enforce tool restrictions or permissions | Planning, building, and testing all share a lot of context |
| The work is self-contained and can return a summary | It's a quick, targeted change |
| You want several independent investigations in parallel | Latency matters, since a fresh subagent has to gather context first |
A few concrete patterns that work:
- Isolate the noise. "Use a subagent to run the test suite and report only the failures." The full output stays in the subagent's window.
- Research in parallel. "Research the auth, database, and API modules in parallel with separate subagents." This works best when the paths don't depend on each other. Each result still lands in your context, so ten detailed reports can cost you what you were trying to save.
- Enforce a boundary. A read-only reviewer with
tools: Read, Grep, Globphysically can't edit your files, whatever its prompt says.
If the side task needs everything you've already discussed, a regular subagent is the wrong fit because it starts blank. Use /subtask to start a fork instead. A fork inherits the whole conversation, runs in the background, and still returns only its result. It also reuses your prompt cache, which makes it cheaper than a fresh subagent for that kind of job.
When the main session itself is running out of room, that's a compaction question rather than a delegation one, and Claude Code handles it differently.
Where Taku fits
Subagents are a sharp tool for people who already live in Claude Code. They assume a working install, a repo, and the patience to tune a description until Claude delegates reliably. Plenty of people see a good agent setup shared online and never get past that first step.
Taku is built for that gap. It's an AI-native desktop workspace where you mirror an AI setup someone already got working, run it, remix it for your own work, and keep it. It doesn't replace Claude Code, and if you're writing your own subagents, Claude Code is the stronger tool for that job. Taku is in Beta, and the Mac app is available now.
FAQ
What are Claude Code subagents?
Specialized workers that Claude delegates tasks to inside a session. Each runs in its own context window, with its own system prompt, tool access, and permissions, and returns a summary instead of its full working.
Where do I put custom subagent files?
In .claude/agents/ for one project, or ~/.claude/agents/ for all your projects. Each subagent is a Markdown file with YAML frontmatter. Only name and description are required.
How does Claude decide when to use a subagent?
It matches your request and the current context against each subagent's description. Naming one in your prompt asks Claude to delegate, but Claude still decides. To guarantee a specific subagent runs, @-mention it. claude --agent test-runner runs the whole session as that subagent.
Why doesn't /agents open the wizard anymore?
As of v2.1.198, the interactive creation wizard was removed. Ask Claude to write the subagent file, or create it in .claude/agents/ yourself. File format and locations are unchanged.
What's the difference between a subagent and a skill?
A skill is reusable instructions that usually run in your main conversation. A subagent is an isolated worker with its own context window. They combine: subagents can preload skills, and skills can run inside a subagent with context: fork.
Are subagents the same as agent teams?
No. Subagents report back to the session that spawned them. Agent teams are several full sessions that message each other and share a task list. Teams are experimental and off by default, and they use more tokens.