What is a Claude Code subagent?
A Claude Code subagent is a helper that the main session starts to do one kind of task. It runs in its own context window, with its own system prompt, its own tool list and its own permissions. When it finishes, only its summary returns to the main conversation.
Use one when a side task would fill your main chat with output you will not need again, such as long search results or log files. A subagent that is not a fork starts fresh. It does not see your chat history or the files Claude already read.
A subagent is not a skill. A skill adds instructions to the main conversation. A plugin can ship subagents, along with skills and hooks, in one install.
To run Claude Code’s agent loop from your own Python or TypeScript code, use the Claude Agent SDK instead.
Which subagents come built in?
Claude Code ships with a few subagents that Claude uses on its own. You do not have to create them.
| Agent | What it does | Tools |
|---|---|---|
| Explore | Searches and reads code. Asked for a quick, medium or very thorough pass. | Read-only; Write and Edit denied |
| Plan | Gathers facts for a plan while you are in plan mode. | Read-only; Write and Edit denied |
| general-purpose | Handles multi-step work that both explores and changes code. | Every tool available to subagents |
| claude-code-guide, statusline-setup | Answers questions about Claude Code features, and sets up the status line. | Built-in helpers |
Explore and Plan start without your CLAUDE.md files and without the git status snapshot, which keeps them fast. Custom subagents load both, unless you set omitClaudeMd.
Where should a subagent file live?
Claude Code reads subagent files from five places. When two share a name, the one with the higher priority wins.
| Location | Scope | Priority |
|---|---|---|
| Managed settings | Whole organization | 1 (highest) |
--agents flag | This session only, not saved to disk | 2 |
.claude/agents/ | This project, shared through version control | 3 |
~/.claude/agents/ | All your projects | 4 |
Plugin agents/ folder | Wherever the plugin is enabled | 5 (lowest) |
Project subagents are the usual choice for a team. Claude Code scans subfolders too, but identity comes only from the name field, not from the folder. Keep names unique across the tree, because two files with the same name can load in an order you cannot count on.
How do you create one?
- Ask Claude to write one, or create the file by hand in
.claude/agents/or~/.claude/agents/. A subagent file is Markdown with a short YAML header. If Claude cannot find a new file, restart Claude Code: a running session does not notice a folder created after it started. - Set
nameanddescription. These are the only required fields. The description tells Claude when to hand off a task, so write it as a trigger. - Add the tools it may use in
tools. If you leave it out, the subagent inherits every tool available to subagents. - Pick a
model:haiku,sonnet,opus,fable, a full model ID, orinherit. If you leave it out, the subagent runs on the model of the conversation that starts it. - Write the system prompt in the body, below the closing
---. Say what to check and how to format the output. - Start a new task and check that Claude calls it. Field names must match exactly, because Claude Code ignores a field it does not recognize without an error. Run
claude --debugand search the log fordoes not recognize or applyto find a typo.
A minimal read-only reviewer looks like this:
1---
2name: code-reviewer
3description: Reviews code for quality, security and missing tests. Use right after code changes.
4tools: Read, Grep, Glob, Bash
5model: inherit
6---
7
8You are a senior code reviewer. Run git diff, review the changed files,
9and group your findings by priority.
The reviewer has no Edit or Write tool, so it cannot change the code it reviews.
Which fields matter most?
| Field | What it controls |
|---|---|
tools / disallowedTools | Which tools it may use, or which to remove |
permissionMode | How it asks for permission (default, acceptEdits, plan and others) |
maxTurns | The turn limit. At the limit, the output comes back marked as partial. |
skills | Skills whose full text loads into its context at start |
isolation: worktree | Runs it in a temporary git worktree, an isolated copy of the repository, cleaned up if it makes no changes |
memory | A notes folder that survives across sessions (see below) |
background | Keeps it running in the background when Claude would otherwise wait |
Plugin subagents ignore hooks, mcpServers and permissionMode, for security. If you need those, copy the file into .claude/agents/ or ~/.claude/agents/.
How do you call a subagent?
- Let Claude decide. Name it in your prompt: “Use the code-reviewer subagent to check my changes.” Claude matches the request against each
description. - @-mention it. Type
@and pick it from the list. This guarantees that subagent runs for the task, but your full message still goes to it. - Run the whole session as it. Start with
claude --agent code-reviewer. The main thread then takes on its tool limits and model.
Claude Code caps nesting. A subagent can start subagents up to three layers below the main conversation by default. It also caps concurrent subagents at 20 by default.
What is the memory field?
The memory field gives a subagent a folder that survives across sessions. Pick a scope:
user:~/.claude/agent-memory/<agent-name>/, for learnings you want in every project.project:.claude/agent-memory/<agent-name>/, shared through version control. Anthropic’s docs call this the recommended default.local:.claude/agent-memory-local/<agent-name>/, for one project, kept out of version control.
When memory is on, Read, Write and Edit are turned on for the subagent, and its prompt gets the first 200 lines or 25 KB of its MEMORY.md. If auto memory is off in your settings, the field has no effect.
This is a set of plain files that the subagent edits. It stores what the subagent writes down, and nothing else. You can ask it to check its memory before a task and to save what it learned after. For the main session’s own memory, see Claude Code memory. For the Codex equivalent, see Codex subagents.
Where does Hindsight fit?
The memory field and Hindsight solve different problems:
- The
memoryfield is a folder of notes that one subagent writes and reads. Claude Code loads the start of itsMEMORY.mdinto the prompt. - Hindsight is a memory server. Its Coding Agents package (one npm install,
npx @vectorize-io/hindsight-coding-agents install claude-code) covers 22 CLI agents, Claude Code among them, and captures sessions automatically, with one memory bank per repository. The old per-agent Claude Code plugin is retired. - What the Coding Agents page does not say: the page I read on 2026-11-14 does not explain how Claude Code subagent runs are captured or recalled. Do not assume a subagent sees the same memory as the main session. Test it: ask the subagent a question that only a past session can answer.
- Strength: Hindsight reports 64.1 on BEAM 10M against Mem0’s 48.6. The BEAM figures come from Mem0’s own comparison page, not from an independent test, so treat them as the vendors’ numbers.
- Limit: Hindsight returns more context per recall than Mem0 by default, and each save calls an LLM. Lower
max_tokensif recall is too large. For a short, single-task subagent, its own notebook may be enough.
Sources
- Claude Code subagent docs, code.claude.com/docs/en/sub-agents (read 2026-11-14): built-in agents, scopes, frontmatter fields, the memory field, model order, concurrency and depth limits, and the examples.
- Hindsight Coding Agents docs, hindsight.vectorize.io/sdks/integrations/coding-agents (read 2026-11-14): the install command and the one-bank-per-repository rule. The page does not describe subagent capture.
- Benchmark figures (BEAM 10M, 64.1 and 48.6): Mem0’s comparison page, not Hindsight’s own report.