---
title: "Claude Code subagents: what they are, when to use them | Bombos"
description: "A Claude Code subagent is a helper with its own context window, prompt and tool limits. It works on a side task and returns only its result to your session."
image: "https://bombos.ai/assets/og-en-v2.png"
---

# What are subagents in Claude Code and when should you use them?

Short answer

A subagent is a separate Claude worker that Claude Code starts for one task. It has its own context window, its own system prompt and its own tool permissions, and it returns only a result, so long search output or logs stay out of your main conversation. Claude Code ships built-in subagents such as Explore and Plan, and you define your own as Markdown files in .claude/agents/.

*Piet Baudoin · published November 17, 2026 · November 17, 2026*

## 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:

1.  Managed settings, for the whole organization
2.  The `--agents` flag, for one session, as JSON
3.  `.claude/agents/` in the repo, for the project
4.  `~/.claude/agents/`, for all your projects
5.  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:

1.  The output is long and you only need the conclusion: test runs, log files, a wide search.
2.  You want a hard limit on what it may do. A reviewer with only `tools: Read, Grep, Glob` cannot edit, and Claude Code enforces that, not the prompt.
3.  You want a second look from something that did not watch the code being written.
4.  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](https://bombos.ai/en/questions/claude-code/claude-code-token-cost-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](https://bombos.ai/en/questions/claude-code/claude-code-skills/) for the team’s procedures. When workers need to talk to each other rather than report back, look at [agent teams](https://bombos.ai/en/questions/claude-code/claude-code-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.

## Sources

1.  [Claude Code docs: Create custom subagents](https://code.claude.com/docs/en/sub-agents)
2.  [Claude Code docs: Best practices](https://code.claude.com/docs/en/best-practices)
3.  [Claude Code docs: Manage costs effectively](https://code.claude.com/docs/en/costs)
4.  [Claude Code docs: Orchestrate teams of Claude Code sessions](https://code.claude.com/docs/en/agent-teams)

## What does your AI forget?

1.  01You tell us which AI you use and where it keeps starting over.
2.  02We show what a shared memory changes there, on your own examples.
3.  03You keep the plan, with or without Bombos.

![Piet Baudoin](https://bombos.ai/assets/team/piet-klein.jpg)

**Piet Baudoin**You talk to Piet, from the Bombos teamDutch team from Utrecht and Nijmegen · data in Europe

## More questions about Claude Code

-   [What is Claude Code Router and should a team use it?](https://bombos.ai/en/questions/claude-code/claude-code-router/)
-   [OpenCode vs Claude Code: which coding agent should I use?](https://bombos.ai/en/questions/claude-code/opencode-vs-claude-code/)
-   [What are Claude Code hooks and how do I set them up?](https://bombos.ai/en/questions/claude-code/claude-code-hooks/)
-   [How do I use Claude Code in VS Code and JetBrains?](https://bombos.ai/en/questions/claude-code/claude-code-in-vs-code-and-jetbrains/)
-   [What is Claude Code Remote Control and how do I use it?](https://bombos.ai/en/questions/claude-code/claude-code-remote-control/)
-   [How much does Claude Code cost per developer per month in tokens?](https://bombos.ai/en/questions/claude-code/claude-code-token-cost-per-developer/)
-   [How do Claude Code usage limits work, and how do I check my usage?](https://bombos.ai/en/questions/claude-code/claude-code-usage-limits/)
-   [Claude Code vs Cursor: which should my dev team choose?](https://bombos.ai/en/questions/claude-code/claude-code-vs-cursor/)

[All questions about Claude Code →](https://bombos.ai/en/questions/claude-code/)


---

```json
{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://bombos.ai/#organization","name":"Bombos","url":"https://bombos.ai/","logo":"https://bombos.ai/assets/bombos-bee.png","description":"Bombos is the memory layer under every AI your team uses. One shared memory for Claude, ChatGPT, Copilot, Cursor and your own agents, that learns how you work.","sameAs":["https://www.linkedin.com/company/bombos-ai","https://www.youtube.com/@truebombos","https://www.instagram.com/truebombos/","https://bsky.app/profile/bombostrue.bsky.social","https://www.threads.com/@truebombos","https://mastodon.social/@Bombos","https://www.tiktok.com/@truebombos","https://t.me/truebombos","https://www.pinterest.com/truebombos/","https://github.com/bombos-ai","https://linktr.ee/bombos.ai","https://bombosai.substack.com","https://hashnode.com/@bombosai","https://hackernoon.com/u/bombos","https://dev.to/bombos"],"email":"info@bombos.ai","areaServed":["NL","Europe"],"knowsLanguage":["nl","en"],"contactPoint":{"@type":"ContactPoint","email":"info@bombos.ai","contactType":"sales","url":"https://bombos.ai/en/contact/","availableLanguage":["nl","en"]}},{"@type":"WebSite","@id":"https://bombos.ai/#website","name":"Bombos","url":"https://bombos.ai/","inLanguage":["nl-NL","en"],"publisher":{"@id":"https://bombos.ai/#organization"}}]}

{"@context":"https://schema.org","@type":"Article","headline":"What are subagents in Claude Code and when should you use them?","description":"A Claude Code subagent is a helper with its own context window, prompt and tool limits. It works on a side task and returns only its result to your session.","abstract":"A subagent is a separate Claude worker that Claude Code starts for one task. It has its own context window, its own system prompt and its own tool permissions, and it returns only a result, so long search output or logs stay out of your main conversation. Claude Code ships built-in subagents such as Explore and Plan, and you define your own as Markdown files in .claude/agents/.","datePublished":"2026-11-17T00:00:00.000Z","dateModified":"2026-11-17T00:00:00.000Z","author":{"@type":"Person","name":"Piet Baudoin"},"publisher":{"@type":"Organization","@id":"https://bombos.ai/#organization","name":"Bombos","logo":{"@type":"ImageObject","url":"https://bombos.ai/assets/bombos-bee.png"}},"image":"https://bombos.ai/assets/og-en-v2.png","mainEntityOfPage":"https://bombos.ai/en/questions/claude-code/claude-code-subagents/","inLanguage":"en-US","isPartOf":{"@type":"CollectionPage","name":"Claude Code","url":"https://bombos.ai/en/questions/claude-code/"},"citation":[{"@type":"CreativeWork","name":"Claude Code docs: Create custom subagents","url":"https://code.claude.com/docs/en/sub-agents"},{"@type":"CreativeWork","name":"Claude Code docs: Best practices","url":"https://code.claude.com/docs/en/best-practices"},{"@type":"CreativeWork","name":"Claude Code docs: Manage costs effectively","url":"https://code.claude.com/docs/en/costs"},{"@type":"CreativeWork","name":"Claude Code docs: Orchestrate teams of Claude Code sessions","url":"https://code.claude.com/docs/en/agent-teams"}]}

{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Bombos","item":"https://bombos.ai/en/"},{"@type":"ListItem","position":2,"name":"Questions","item":"https://bombos.ai/en/questions/"},{"@type":"ListItem","position":3,"name":"Claude Code","item":"https://bombos.ai/en/questions/claude-code/"},{"@type":"ListItem","position":4,"name":"What are subagents in Claude Code and when should you use them?","item":"https://bombos.ai/en/questions/claude-code/claude-code-subagents/"}]}

{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[{"@type":"Question","name":"Do subagents cost extra?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Can a subagent start its own subagents?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Does a subagent see my conversation?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"How do I call a specific subagent?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"What is the difference with agent teams?","acceptedAnswer":{"@type":"Answer","text":"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."}}]}
```
