What is a subagent?
A subagent is a helper agent that a main coding agent starts to hand off a specific job. It has its own context window, instructions and tool permissions, and when it finishes it returns only a summary, so the main conversation doesn’t fill up with detail.
How it works
The main agent hands a job to a subagent, such as searching the codebase, running tests and summarizing failures, or reviewing a change. The subagent starts with a clean context; the files it reads and the command output it sees stay in its own window, and the main agent gets only the result. Several subagents can run at the same time.
Defining subagents in Claude Code
In Claude Code, subagents are Markdown files with YAML frontmatter. Project subagents live in .claude/agents/ and personal ones in ~/.claude/agents/; you can also manage them with the /agents command.
- name and description: what the subagent is called and when to use it. The main agent decides based on this description.
- tools: which tools it may use, for example only read tools for a reviewer.
- model: optionally, a different model for the subagent.
- The body of the file is the subagent’s system prompt.
When subagents help
Subagents pay off most when you want to keep the main conversation clean.
- Research that reads many files: the detail stays in the subagent and the main context stays small.
- Specialist roles: security review, writing tests, documentation.
- Parallel exploration: several subagents scan different modules at once.
Limits
A subagent doesn’t see the main conversation’s history, so the task it’s given has to stand on its own. Because each subagent builds its own context from scratch, total token use can go up. Subagents usually work in the same folder as the main agent, so parallel subagents that edit files can get in each other’s way.
Subagents in AgentVera
AgentVera makes the subagents Claude Code starts visible. The Subagents view in the project tour and code map window lists the subagents a Claude Code agent started.
- For each one: type, whether it ran in the background, status, tool count and duration, plus a timeline of its steps.
- It reads local transcripts and works with local Claude Code agents for now.
- The Task line and Research, plan, build use separate, visible agents instead of subagents: each stage has its own pane and hands off through files (Pro and Team).
- Project tour and code mapGet to know a project with a tour, see module dependencies and the files that break most.
- Task lineQueue tasks and let each pass through Analysis, Plan, Build and Review agents in order.
- Research, plan, buildA one-click three-agent pipeline: research notes, a plan, then the build, handed off through files.
FAQ
How is a subagent different from a separate agent session?
The main agent starts a subagent and gets its result back; you usually see only the summary. A separate session runs on its own and you talk to it directly.
Do subagents save tokens?
They keep the main conversation’s context small, which helps in long sessions. But the subagent’s own reading costs tokens too, so total usage can rise.
Can a subagent edit files?
That depends on the tools its definition allows. A subagent given only Read, Grep and Glob can read code but not change it.
Where should I put subagent files?
Ones your team should share go in .claude/agents/ in the project; ones only you use go in ~/.claude/agents/. Files in the project folder reach your team through git.