Claude Code subagents are helpers that the main Claude Code session hands a single task to. Each one runs in its own context window, with its own system prompt, tool list and model, and only its final answer comes back to the main conversation. You define a subagent as a Markdown file in .claude/agents/, and Claude uses it automatically when the task matches its description, or when you ask for it by name.
This post covers how subagents work, the file format, the tools and model fields, how to call them, and the line between a subagent and a separate agent running next to the first one. Facts come from the official subagents docs. For the one-paragraph version, see the subagent glossary entry.
How subagents work
When Claude decides to delegate, it calls the Agent tool (called Task before version 2.1.63) with a short brief. The subagent starts with a fresh context. It gets its own system prompt, the delegation message, your CLAUDE.md, the git status and any skills you preloaded for it. It does not see the main conversation history.
It then works through the task with its allowed tools and returns one result. Everything it read along the way, such as dozens of files, long grep output or test logs, stays in its own context. That is the main reason to use subagents: the main conversation gets a summary, not the noise.
A few limits worth knowing:
- Subagents can start their own subagents, up to three layers deep by default.
- Up to 20 can run at once by default.
- Their requests count toward the same usage limits as the main session.
- A subagent can run in the foreground, where the main agent waits, or in the background while the main agent keeps going.
Built-in subagents
Claude Code ships a few subagents you can use without writing anything:
| Subagent | Tools | Typical use |
|---|---|---|
| Explore | Read only | Searching and reading across the codebase, at quick, medium or very thorough depth |
| Plan | Read only | Research while in plan mode |
| General-purpose | All tools | Multi-step tasks that need both research and changes |
Explore is the one you will see most. When Claude needs to find where something is defined or how a feature works across files, it often hands that to Explore so the file dumps don’t land in your main context.
Where subagent files live
Subagents are Markdown files with YAML frontmatter. Claude Code loads them from several places, and when two have the same name, the higher one in this list wins:
| Location | Scope |
|---|---|
| Managed settings | Organization-wide, set by admins |
--agents flag (JSON) | One session |
.claude/agents/ | One project, shared through git |
~/.claude/agents/ | All your projects |
A plugin’s agents/ folder | Wherever the plugin is installed |
Project subagents in .claude/agents/ are the ones to commit, so the whole team shares the same reviewer or test runner.
The subagent file format
Only name and description are required. The body after the frontmatter is the subagent’s system prompt.
---
name: code-reviewer
description: Reviews code changes for bugs, security issues and readability. Use after writing or changing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a senior code reviewer. When called:
1. Run git diff to see the recent changes.
2. Read the changed files and the code around them.
3. Report problems by priority: bugs, security, then readability.
4. For each problem, give the file, the line and a concrete fix.
Do not edit files. Report only.The description matters more than it looks. It is what Claude reads when deciding whether to delegate, so say what the subagent does and when to use it. Phrases like “use after writing code” help Claude pick it up on its own.
The tools field
tools is an allowlist. With tools: Read, Grep, Glob, Bash, the reviewer above can read and run commands but cannot edit files. If you leave tools out, the subagent inherits every tool the main session has, including MCP tools. There is also disallowedTools when it is easier to say what to remove than what to keep.
Keep the list as short as the job allows. A reviewer does not need Edit. A researcher does not need Bash. Fewer tools means fewer surprises and a clearer job.
The model field
model accepts an alias (sonnet, opus, haiku), a full model ID, or inherit to use the main session’s model. When the subagent is called, Claude Code picks the model in this order: a model passed with that call, then the file’s model field, then the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then the main session’s model.
This is where subagents can save real money. Broad file searches and log reading rarely need the strongest model. Put them on Haiku and keep the main session on the bigger model for the decisions. The Claude Code token usage post covers more ways to cut spend.
Other useful fields
| Field | What it does |
|---|---|
permissionMode | Permission mode for the subagent, for example plan or acceptEdits |
skills | Skills to load into the subagent’s context at start |
mcpServers | MCP servers the subagent can use |
hooks | Hooks that apply while this subagent runs |
memory | Persistent memory at user, project or local scope |
maxTurns | Upper limit on the subagent’s turns |
background | Run in the background by default |
isolation: worktree | Run in a temporary git worktree |
effort | Reasoning effort for the subagent |
How to call a subagent
There are three ways:
- Let Claude decide. If the request matches a subagent’s description, Claude delegates on its own.
- Ask by name. “Use the code-reviewer subagent to check my last commit.” You can also @-mention it from the menu.
- Run a whole session as one.
claude --agent code-reviewerstarts a session that uses that subagent’s prompt, tools and model.
For a one-off session you can pass subagents as JSON without creating files:
claude --agents '{
"code-reviewer": {
"description": "Reviews code changes. Use after edits.",
"prompt": "You are a senior code reviewer. Report bugs and fixes, do not edit.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
}
}'To stop Claude from using a particular subagent, add it to the deny list in your permissions, for example Agent(Explore).
Subagents vs separate parallel agents
Subagents and parallel agents both split work, but they solve different problems.
| Subagents | Separate parallel agents | |
|---|---|---|
| Who starts them | The main Claude session | You |
| What you see | The final result, inside the main chat | Each agent’s full session |
| Context | Fresh per task, discarded after | Long-lived, one per agent |
| Files | Same working folder unless isolation: worktree | Usually one git worktree each |
| Your input mid-task | None, the main agent talks to it | You can steer each one |
| Good for | Search, review, research, short focused jobs | Features, refactors, long tasks that end in a branch |
Use a subagent when the main agent needs an answer to keep going: “find every caller of this function”, “review this diff”, “summarize these logs”. The work is short, its result is what matters, and you don’t need to watch it.
Use separate agents when each piece is real work on its own: a feature, a migration, a test suite. You want to see what each one is doing, answer its questions, and review its changes as a branch. That is the setup described in parallel coding agents and running multiple Claude Code agents, with each agent in its own git worktree.
The two mix well. A separate agent can still use subagents for its own searches and reviews. A good default is separate agents for the work you would assign to a person, and subagents for the errands those agents run. For larger teams, the AI agent team post covers roles and hand-offs, and the multi-agent orchestration entry covers the general idea.
Claude Code also has a separate feature called agent teams, where several Claude sessions work together. That is not the same as subagents and is outside this post.
Tips for subagents that work
- One job per subagent. “Reviewer” and “test runner” work better than “helper”.
- Write the description for Claude. Say when to use it, not just what it is.
- Limit tools. Read-only subagents for research and review, edit tools only where needed.
- Pick the model on purpose. Haiku for search and summaries, a stronger model for design and tricky fixes.
- Ask for a short report. The result goes into the main context, so tell the subagent to return findings, not file dumps.
- Check in your project subagents.
.claude/agents/in git means everyone gets the same helpers.
How AgentVera shows subagents
AgentVera is a desktop app for running many coding agents, Claude Code, Codex and others, side by side. It handles subagents in two ways.
You can see them. In a Claude Code agent’s pane, the “Subagents” button opens a live view of the subagents that agent started and what they are doing now. Each one shows its status (Running, Done, Error, Stopped), whether it runs “in background”, the “Assigned task” it got and its “Report”. While some are working, a “{count} subagents running — show” line appears so you don’t miss them. The project tour and code map also has a subagents timeline with type, status, tool count and duration. Both read local transcripts and are for Claude Code agents for now.
A cheaper Explore. Under Settings → “Token saving”, the “Explorer subagent” option gives Claude agents a read-only explorer for broad searches. File scanning runs on a cheaper model, Haiku by default, and only the result returns to the main conversation. If you already have your own Explore subagent file, AgentVera leaves yours in place. It sits next to the smart tools in the same section.
Separate agents when the work is bigger. The team view shows up to 24 agents at once. Parallel team (Pro and Team plans) splits a goal into parts, runs each in its own worktree and merges them into one PR. Agent messaging lets agents ask each other questions, even across CLIs, and agent coordination warns when two agents touch the same file. That gives you the separate-agent side of the table above, with subagents still available inside each Claude agent.
Wrapping up
Subagents are the right tool when the main agent needs an answer and you don’t need to watch the work: search, review, research. Write one Markdown file with a clear description, a short tool list and a deliberate model. When the work is big enough to deserve its own branch and your attention, run a separate agent instead.
Read more:
- Subagent (glossary)
- Parallel coding agents
- Project tour and code map
- Parallel team
- Claude Code agent
To try AgentVera, start at the home page.