Skip to content

Claude Code subagents

By Mari Luukkainen · 5 min read · Last updated

On this page

A Claude Code subagent is a separate Claude instance with its own context window, system prompt and tool access. Claude hands it a task, it does the reading or work, and only its summary comes back to your main conversation. Three are built in (Explore, Plan and general-purpose), and you can define your own as Markdown files in .claude/agents/. Facts here come from Anthropic's subagents docs, checked 11 November 2026.

Subagents are one of the add-ons covered in what Claude Code is. Their requests count toward the same usage limits as the main conversation, so several running at once use your allowance faster; the plans and limits are on Claude Code pricing.

Ask AI about this pageChatGPTClaudePerplexityGoogle AI ModeGrok

What are subagents for?

The main use is keeping noise out of your context. Searching a large codebase, reading logs or running a long test suite produces pages of output you do not need to keep. A subagent reads all of it in its own context and returns a short summary. Anthropic also lists two other reasons: you want a worker with fewer tools or stricter permissions, or the job is self-contained and can be handed off (subagents docs).

Stay in the main conversation for back-and-forth work, for quick targeted edits and when several steps need the same context. A new subagent starts fresh and does not see your conversation history, the skills you ran or the files already read, so Claude has to write it a task message that carries everything it needs.

Which subagents are built in?

SubagentToolsUsed for
ExploreRead-only, cannot write or editFast search and analysis of the codebase. Claude picks a thoroughness level: quick, medium or very thorough
PlanRead-only, cannot write or editResearch during plan mode, so the main session stays read-only
general-purposeAll tools available to subagentsMulti-step tasks that need both exploring and changing files
claudeAll tools available to subagentsA catch-all for tasks that fit no specialised agent
statusline-setupNot listedRuns when you use /statusline
claude-code-guideNot listedAnswers questions about Claude Code itself

Explore and Plan start without CLAUDE.md and without the git status snapshot. To switch off Explore, add "Agent(Explore)" to permissions.deny; denying the Agent tool stops all delegation (subagents docs).

How do you create your own subagent?

Ask Claude to write one, or create the file yourself. A subagent is a Markdown file with YAML frontmatter; the body becomes its system prompt. It gets that prompt plus basic environment details, without the full Claude Code system prompt.

.claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews the current diff for bugs, missing checks and unclear names. Use after code changes, before a commit.
tools: Read, Glob, Grep, Bash
model: sonnet
---

You review code. Run git diff to see the changes. Report problems as a list with file and line, most serious first.
Do not edit files. If you find nothing worth fixing, say so in one line.
LocationApplies toPriority when names collide
Managed settingsThe organization1 (highest)
--agents flag with JSONThis session only2
.claude/agents/This project3
~/.claude/agents/All your projects4
A plugin's agents/ folderWhere the plugin is enabled5

Changes to agent files are picked up within seconds. A restart is needed only when you create the first agents folder for a scope (subagents docs).

Which frontmatter fields can you set?

Only name and description are required. Field names are case-sensitive, and unknown fields are ignored without a warning.

  • description. When Claude should hand work to this agent. Words such as "use proactively" make automatic delegation more likely.
  • tools and disallowedTools. An allowlist and a denylist. Leave tools out to inherit every tool subagents can use. MCP tools work too, such as mcp__github__*.
  • model. sonnet, opus, haiku, fable, a full model ID or inherit.
  • permissionMode. default, acceptEdits, auto, dontAsk, bypassPermissions or plan. If the main session is in bypassPermissions, acceptEdits or auto mode, the subagent inherits that and ignores this field.
  • maxTurns. A cap on agentic turns. Output is marked partial when the cap is hit.
  • skills. Skills loaded in full when the agent starts. See Claude Code skills.
  • hooks. Hooks that apply only while this agent runs. See Claude Code hooks.
  • isolation: worktree. Runs the agent in a temporary git worktree, so its edits do not touch your checkout.
  • background: true. Keeps the agent in the background while you keep working.

Plugin subagents ignore hooks, mcpServers and permissionMode (subagents docs).

How do you call a subagent?

  • Let Claude decide. It delegates when a request matches an agent's description.
  • Ask in plain language: "use the code-reviewer subagent to check my changes".
  • @-mention it to guarantee it runs: @"code-reviewer (agent)" followed by the task.
  • Run a whole session as that agent with claude --agent code-reviewer, or set "agent" in .claude/settings.json.

A foreground subagent blocks the main conversation until it reports. A background subagent runs alongside, and its permission prompts appear in your main session. Each call starts a new instance; Claude can resume an earlier one by its ID, except Explore and Plan, which are one-shot (subagents docs).

What are the limits?

LimitDefaultChange it with
NestingSubagents can start their own, up to three layers below the main conversationCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (1 turns nesting off)
Running at once20 subagentsCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS
Total per sessionNo limitNone needed
DescriptionsA startup warning when custom agent descriptions together pass 15,000 tokensShorter descriptions, detail moved into the body

Source: subagents docs, checked 11 November 2026. Parallel subagents draw on the same allowance at the same time, so start with one and add more only when the work splits cleanly.

Frequently asked questions

What is a subagent in Claude Code?

A separate Claude instance with its own context window, system prompt and tools. Claude gives it a task and gets back a summary, so the detail stays out of your main conversation.

Where are Claude Code subagents stored?

In .claude/agents/ for one project and ~/.claude/agents/ for all your projects, as Markdown files with YAML frontmatter.

Can a subagent start another subagent?

Yes, up to three layers below the main conversation by default. Set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH to 1 to turn nesting off.

Do subagents use more of my Claude plan?

Their requests count toward the same usage limits as your main conversation. Several running in parallel use the allowance faster.

Can a subagent use a different model?

Yes. Set model in its frontmatter to sonnet, opus, haiku, fable, a full model ID or inherit. Without it, the subagent uses CLAUDE_CODE_SUBAGENT_MODEL if set, otherwise the main conversation's model.

Next guideClaude Code plan mode →