Claude Code — Subagents · AI coding agents

Subagents are specialized agents Claude Code delegates work to. Each runs with its own context window, its own tool set, and (optionally) its own model — so a research-heavy task doesn’t pollute the main conversation.

Where they live

Source	Location	Scope
CLI flag	`--agents '<json>'`	Session only (highest priority)
Project	`.claude/agents/*.md`	Committed, shared with the team
User	`~/.claude/agents/*.md`	Personal, all projects
Plugin	`<plugin>/agents/`	Bundled with a plugin

Priority on name conflicts: --agents flag > project > user > plugin.

Defining a subagent

A subagent is a Markdown file with YAML frontmatter:

---
name: api-reviewer
description: Reviews API route handlers for correctness, error handling, and consistency with the OpenAPI spec. Use proactively after changes to app/api/.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are an API reviewer for this codebase. When invoked:

1. Read every changed file under `app/api/`.
2. Check error responses match the shapes in `openapi.yaml`.
3. Verify input validation exists for all query/body params.
4. Report findings as a numbered list, severity-tagged (blocker / warning / nit).

Do not modify files — report only.

Frontmatter fields (verified)

Field	Required	Purpose
`name`	yes	Lowercase + hyphens; how the agent is referenced
`description`	yes	Used for auto-delegation — Claude decides when to invoke the agent based on this text
`tools`	no	Tool allowlist; inherits all tools (incl. MCP) if omitted; supports `Task(agent_type)` to restrict which subagents it can spawn
`disallowedTools`	no	Tools to withhold
`model`	no	`sonnet` / `opus` / `haiku` / `inherit` (default `inherit`)
`permissionMode`	no	`default` / `acceptEdits` / `dontAsk` / `bypassPermissions` / `plan`
`maxTurns`	no	Cap on agentic turns
`skills`	no	Skills preloaded at startup
`mcpServers`	no	MCP servers available to the agent
`hooks`	no	Agent-scoped hooks
`memory`	no	`user` / `project` / `local` — persistent memory in `~/.claude/agent-memory/<name>/` etc.; first 200 lines of `MEMORY.md` are injected
`background`	no	Always run in the background
`isolation`	no	`worktree` — run in a temporary git worktree

Built-in subagents

Explore — read-only codebase search (Haiku), with thoroughness levels: quick / medium / very thorough.
Plan — read-only research during plan mode.
general-purpose — all tools, inherits the model.
Helpers: Bash, statusline-setup (Sonnet), Claude Code Guide (Haiku).

Invoking subagents

Automatically — Claude delegates based on each agent’s description; writing “Use proactively…” in the description nudges earlier delegation.
Explicitly — just ask: “use the api-reviewer subagent to check my changes”.
/agents — manage subagents (since v2.1.198 it reminds you to ask Claude or edit .claude/agents/ directly; older versions open an interactive UI).
claude agents — list all configured subagents from the shell, no session needed.
claude --agent <name> — run the whole session as a given agent (it becomes the main thread and can spawn subagents via Task).

Use cases

Read-only exploration without burning main-context tokens (Explore).
Parallel independent workstreams (agents run in the background by default since W27 2026).
Specialists with narrow tools: a reviewer that can only read, a migration agent with a fixed prompt.

Limitations

The sub-agents reference states subagents cannot spawn other subagents (this prevents infinite nesting). A June 2026 “What’s new” entry says subagents can spawn their own subagents — the docs conflict; current behavior: ? Unable to verify.
Background subagents auto-deny any permission not pre-approved and can’t ask clarifying questions.
Transcripts are stored at ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl and are resumable by agent ID.
Auto-compaction applies to subagents too (~95% of context by default; CLAUDE_AUTOCOMPACT_PCT_OVERRIDE).

Disabling a subagent

{
  "permissions": {
    "deny": ["Task(Explore)"]
  }
}

or per session:

claude --disallowedTools "Task(Explore)"

Last verified: 2026-09-07

Official sources:

AI coding tools evolve quickly. If you find outdated information, please open an issue or pull request.