How a subagent works
When a task matches a subagent’s description, Claude hands it over. The subagent runs in its own context window with a custom system prompt and its own tool access, does the work, and sends back only the result. A wide codebase search or a full test run then fills the subagent’s context instead of yours.
A subagent does not start from your conversation. Its starting context is its system prompt, the delegation message Claude writes, your CLAUDE.md files, a git status snapshot and any skills you preload. It has not seen what you discussed, so the task Claude hands over has to stand on its own. Forks are the exception: they inherit the conversation. A subagent configured with the memory field also loads its own persistent memory directory.
Claude Code already delegates without being asked. Broad searches go to the built-in Explore agent, and with default settings the subagents Claude starts from the main conversation run in the background, so you can keep working. Press Ctrl+B to send a running task to the background yourself.
The built-in subagents
| Name | What it does |
|---|---|
| Explore | Fast, read-only codebase search, at a thoroughness Claude picks |
| Plan | Read-only research while you are in plan mode |
| general-purpose | Multi-step tasks that need both exploring and changing files |
| claude-code-guide | Answers questions about Claude Code itself, on Haiku |
Explore and Plan skip CLAUDE.md and the git status snapshot to stay fast and cheap.
Define your own in .claude/agents
A custom subagent is a Markdown file with YAML frontmatter. Only name and description are required; the body becomes the system prompt.
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
Where the file lives decides who has it. When names collide, the higher one wins:
- Managed settings, for the whole organization
- The
--agentsflag, for one session, as JSON .claude/agents/in the repo, for the project~/.claude/agents/, for all your projects- A plugin’s
agents/folder, where the plugin is enabled
Other fields worth knowing: disallowedTools, permissionMode, maxTurns, skills to preload skill content, mcpServers, hooks, effort, isolation: worktree to work in a temporary git worktree, and memory for a persistent memory folder per agent (user, project or local). With memory: project, the agent keeps notes in .claude/agent-memory/<name>/, which you can commit. Plugin subagents ignore hooks, mcpServers and permissionMode for security reasons.
You can ask Claude to write the file for you. Changes to existing agent folders are picked up within seconds.
When to use one
Use a subagent when:
- The output is long and you only need the conclusion: test runs, log files, a wide search.
- You want a hard limit on what it may do. A reviewer with only
tools: Read, Grep, Globcannot edit, and Claude Code enforces that, not the prompt. - You want a second look from something that did not watch the code being written.
- Independent pieces of work can run at the same time.
Stay in the main conversation for back-and-forth work, for steps that share a lot of context, and for quick, targeted changes. A fresh subagent first has to gather context your session already has, so it can be slower than doing it yourself.
The misunderstanding: “a subagent gives a better answer”
The Claude Code best practices list this as advice you can drop. By default a subagent is the same model, or a smaller one, on the same task. You get parallel work, a clean context or a fresh pair of eyes, not a smarter answer. And it costs tokens: every subagent sends its own requests, which count toward the same limits as your session. Setting model: haiku on simple agents and checking /usage keeps that in view. More in what Claude Code costs per developer.
What this means for a team
A subagent committed to .claude/agents/ gives every developer the same reviewer or test runner, with the same tool limits. Combine it with skills for the team’s procedures. When workers need to talk to each other rather than report back, look at agent teams. What a subagent learns in a run does not spread, though. Its optional memory folder belongs to that one agent definition, in Claude Code only.
Where Bombos fits
Ordinary subagents start fresh every time, with only the task and the files they are given. Bombos is a plugin that gives Claude Code and the team’s other AI tools one shared memory to draw from: team knowledge, rules learned from earlier corrections, and what is already in mail, documents and repos, each traceable to its source. One developer can try it on their own agents first.
Related questions
Do subagents cost extra?
They use tokens on top of your main conversation, because every subagent sends its own requests, and those count toward the same usage limits. You can lower the cost by setting model: haiku for simple jobs, and /usage shows what share each subagent type takes.
Can a subagent start its own subagents?
Yes, up to three layers below the main conversation by default. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH changes that, and setting it to 1 turns nesting off.
Does a subagent see my conversation?
Not an ordinary one. It starts fresh with its own system prompt, the task Claude writes for it, CLAUDE.md (unless omitClaudeMd is set), a git status snapshot and any preloaded skills. It does not see your history or the files you already read. A fork is the exception: it inherits the conversation. A subagent with the memory field also loads its own persistent memory.
How do I call a specific subagent?
Ask for it by name in plain language, @-mention it as @"code-reviewer (agent)", or start the whole session as that agent with claude --agent code-reviewer.
What is the difference with agent teams?
Subagents report back to the session that started them. In an agent team, which is experimental and off by default, teammates are full sessions that share a task list and message each other directly.
