Subagents
Subagents are isolated Claude instances spawned within your session via the Agent tool. Each runs in its own context window with a custom system prompt and restricted tool access. They report back only to you — they cannot message each other.
Built-in subagents
| Type | Model | Tools | Purpose |
|---|---|---|---|
Explore | Haiku | Read-only | Codebase search and analysis. Thoroughness: quick/medium/very thorough |
Plan | Inherits | Read-only | Research for plan mode. Cannot spawn nested subagents |
general-purpose | Inherits | All tools | Complex multi-step tasks |
Bash | Inherits | Bash | Terminal commands in separate context |
Claude Code Guide | Haiku | Read + Web | Claude Code documentation lookup |
statusline-setup | Sonnet | Read + Edit | Status line configuration |
Custom subagents
Define custom subagents as Markdown files in .claude/agents/ (project) or
~/.claude/agents/ (global), or use /agents to create interactively.
---
name: code-reviewer
description: Review code for security and style issues
tools: Read, Grep, Glob
disallowedTools: Write, Edit
model: sonnet
permissionMode: default
maxTurns: 20
skills:
- api-conventions
mcpServers:
- slack
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate.sh"
memory: user
background: false
isolation: worktree
---
You are a code review specialist...
Supported frontmatter fields
| Field | Required | Description |
|---|---|---|
name | Yes | Unique identifier (lowercase, hyphens) |
description | Yes | When Claude should delegate to this subagent |
tools | No | Tools the subagent can use. Inherits all if omitted |
disallowedTools | No | Tools to deny |
model | No | sonnet, opus, haiku, or inherit (default) |
permissionMode | No | default, acceptEdits, dontAsk, bypassPermissions, plan |
maxTurns | No | Maximum agentic turns |
skills | No | Skills to preload (full content injected at startup) |
mcpServers | No | MCP servers available to this subagent |
hooks | No | Lifecycle hooks scoped to this subagent |
memory | No | Persistent memory scope: user, project, or local |
background | No | true to always run as background task |
isolation | No | worktree for isolated git worktree |
Scope precedence (highest → lowest)
--agentsCLI flag (current session only, JSON).claude/agents/(current project)~/.claude/agents/(all projects)- Plugin
agents/directory
Key features
- Persistent memory: Set
memory: user|project|localfor cross-session learning. The subagent gets a persistent directory at~/.claude/agent-memory/<name>/. - Skill preloading:
skillsfield injects full skill content at startup. - Isolation:
isolation: worktreeruns in a temporary git worktree. - Background execution:
background: trueor pressCtrl+Bto run concurrently. - Resumable: Each invocation gets an agent ID; ask Claude to resume for continuity.
- Auto-compaction: Subagents compact at ~95% capacity (configurable via
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE).
Key constraints
- Subagents cannot spawn other subagents (no nesting).
- Use
run_in_background: truefor tasks over ~30 seconds. - Background tasks: press
Ctrl+Bto continue working in main session. - Results return to your main context — many verbose subagents can still bloat it.
- Disable specific subagents: add
Agent(name)topermissions.denyin settings. - Restrict spawning: use
Agent(worker, researcher)intoolsfield to allowlist.
Subagents are for isolation and parallelism within one session. Agent Teams are for coordination across separate sessions.