Claude Code subagents: delegate work and keep your context clean

A context window is a workbench. Explore a large codebase and you pile file after file onto it, until the actual task is buried under thirty file dumps. Subagents solve exactly that: Claude hands a subtask to a second Claude that works on its own bench and passes back only the result. This article shows which subagents ship with Claude Code, how to define your own, how they are invoked and what they can see. It is based on the official documentation as of September 2026.

What a subagent is and when it pays off

A subagent is a separate Claude run with its own context window, its own system prompt and its own selection of tools. The main session phrases a task, the subagent works through it and returns a report. Everything it reads and tries along the way stays with it. That pays off in three situations:

• Research in large codebases. “Find out how our auth system refreshes tokens” reads twenty files; only the answer lands in the main context.
• Recurring roles with their own rules. A code reviewer that may only read, or a test runner that stops after 25 rounds.
• Parallel work. Several subagents run at the same time, each with its own context and, if you want, each in its own git worktree.

It does not pay off for a single question whose answer you want to see anyway. The report is a summary; if you need the files themselves, read them in the main session.

The three built-in subagents

Three built-in subagents cover everyday work; three more special agents exist for the status line, for questions about the Claude Code documentation and as a catch-all, and you rarely address them directly. The three for everyday work:

Agent	Purpose	Tools	Notable
Explore	fast search and analysis in the code	read-only, Write and Edit denied	skips CLAUDE.md and git status so research stays fast and inexpensive
Plan	research in plan mode	read-only	like Explore, one-shot, cannot be resumed
General-purpose	multi-step tasks	every tool available to subagents	can be continued via SendMessage

Explore and Plan are one-shot agents: they cannot be resumed. If you do not want the built-in agents, disable them with the environment variable CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1.

Defining your own subagents

A custom subagent is a markdown file with YAML frontmatter. The frontmatter describes the agent, the body is its system prompt. There are five places to put it, in this order of priority:

• managed settings of the organisation
• the --agents flag at launch, for this session only
• .claude/agents/ in the project, shared via git
• ~/.claude/agents/ for all your projects
• the agents/ directory of an enabled plugin

The project and user directories are scanned recursively, so subfolders are fine. A complete example:

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code for quality, security and conventions. Use after every larger change.
tools: Read, Glob, Grep
model: sonnet
permissionMode: default
memory: project
---

You are a code reviewer. Analyse the named files and report, per finding:
file and line, the problem, why it is one, and a concrete suggestion.
Change nothing.

The frontmatter fields

Only name (lowercase letters and hyphens) and description are required. The description decides when Claude picks the agent on its own, so it should say what for and when. The remaining fields are optional:

Field	Effect
tools	allowlist of tools; without it the agent inherits everything available
disallowedTools	denylist, for example Write, Edit for a pure reader
model	sonnet, opus, haiku, fable, a full model ID or inherit
permissionMode	default, acceptEdits, plan and others
maxTurns	upper bound of tool rounds before the agent stops
skills	skills preloaded in full into the context at startup
mcpServers	MCP servers available to the agent
memory	user, project or local: the agent’s own auto memory
isolation	worktree: the agent works in its own git worktree
background	true: stays in the background even when Claude wants to run it in the foreground
effort	effort level from low to max
color	display colour in the interface

You do not have to write the file by hand. One sentence in the session is enough: “Create a personal code-improver subagent in ~/.claude/agents/ that reads files and suggests improvements for readability and performance.” Claude writes the file, you check the frontmatter.

Invoking subagents

Four routes lead to an agent, and they differ in who decides:

• Automatically. Claude chooses based on the task and the description. The clearer the description, the better the choice. The combined descriptions of all custom agents should stay under 15,000 tokens, otherwise Claude Code warns you at startup.
• By name in the prompt. “Have the code-reviewer subagent look at my recent changes.”
• By @-mention. @"code-reviewer (agent)" look at the auth changes, or typed as @agent-code-reviewer. Plugin agents are addressed as @agent-plugin:name.
• As the main session. claude --agent code-reviewer starts the session directly as that agent; the same can be fixed with "agent": "code-reviewer" in .claude/settings.json.

A subagent that has delivered a result can be continued: Claude sends it another message via SendMessage, and the agent carries on with its previous context. That does not apply to Explore and Plan.

What a subagent sees and what it does not

The most common mistake on first use: the subagent does not know what you have just been talking about. It receives:

• its own system prompt, that is the body of the agent file, plus environment details; not the Claude Code system prompt
• the task that Claude phrases for it
• the CLAUDE.md files in their full hierarchy (except Explore and Plan)
• a snapshot of the git status from session start
• the skills listed in the skills field, loaded in full

It does not receive the conversation history, the main session’s auto memory or earlier skill invocations. If you want an agent that knows the whole conversation, use a fork: /subtask draft unit tests for the parser changes so far inherits system prompt, tools, model and history, but isolates its tool calls and returns only the result.

Some tools are never available to subagents, among them asking you questions, switching to plan mode and spawning further agents once the nesting depth is reached. By default three levels are allowed and 20 agents at once; both values can be changed through CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH and CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.

Three recipes from practice

The reader that touches nothing

For reviews and research. The allowlist is the safer choice here: whatever is not on it stays out, including every MCP tool added later. If you want the agent to keep read-only MCP tools, use the denylist instead and exclude anything that writes, for example disallowedTools: Write, Edit, NotebookEdit, Bash, mcp__github.

---
name: reader
description: Reads code and documents and reports. For reviews, research and inventories.
tools: Read, Grep, Glob
model: sonnet
---

You read and report. Every finding names file and line. You change nothing.

The test runner with an exit

For “run the tests and fix what is red”. Without maxTurns such an agent can circle for a long time:

---
name: test-runner
description: Runs the test suite and fixes failing tests. Use after changes to logic.
tools: Read, Edit, Bash, Grep, Glob
maxTurns: 25
permissionMode: acceptEdits
---

Run `pnpm test`. Fix failures one at a time and re-run only the affected
test afterwards. Report at the end what turned green and what stayed open.

The refactorer in its own worktree

For mechanical changes across many files that must not disturb the main session. isolation: worktree gives the agent its own copy of the repository; details in the article on worktrees in Claude Code.

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

Troubleshooting

• Claude never picks the agent on its own. The description says what the agent is, but not when it is due. Add the trigger: “Use after every change to migrations.”
• The agent does not know a rule. It was only said in conversation. Whatever every agent must know belongs in CLAUDE.md; every custom agent receives it, only Explore and Plan do not.
• The agent runs without end. Set maxTurns and cut the task smaller.
• Two agents write to the same file. Either run them one after the other, or separate both with isolation: worktree.

Conclusion

Subagents are not a trick for advanced users but the answer to an everyday problem: the main context should carry the task, not the research. Start with the built-in agents, define your first custom one as soon as you describe the same role for the third time, and give each agent only the tools its role needs.

Further reading

• Claude Code worktrees: parallel sessions without collisions
• How to create and structure CLAUDE.md
• Claude Code hooks: a practical guide with recipes