Subagents

A subagent is an isolated AI worker that handles a side task in its own context window and returns only the result to your main conversation — keeping your main session clean and focused.

Why use a subagent

Every Claude Code session has a context window — a finite budget of tokens that holds your conversation, files, and tool results. When you run a task that produces a lot of output (test logs, search results, documentation fetches), that output fills your context and buries the things you actually need to reference later. A subagent handles that noisy work in a separate context window and returns only a summary. Your main conversation stays compact and on-topic.

Preserve context: keep verbose output out of your main conversation
Enforce constraints: limit which tools a subagent can use (e.g., read-only access)
Control costs: route lightweight tasks to faster, cheaper models like Haiku
Reuse configurations: define a specialist once and invoke it across every project

Built-in and custom agents

Claude Code ships with three built-in subagents that Claude invokes automatically — you do not need to configure them.

Explore — fast, read-only codebase search using the Haiku model. Skips your CLAUDE.md files for speed.
Plan — read-only research used when you are in plan mode. Keeps exploration out of your main context.
General-purpose — full tool access, inherits your model; handles complex multi-step tasks.

Fresh context, every time

Each subagent starts with an empty conversation. It does not see your chat history or the files Claude has already read. Claude writes a delegation message that describes the task, and the subagent works from there.

Create a custom subagent

The easiest way is the /agents command. Run it inside Claude Code, switch to the Library tab, click Create new agent, and follow the prompts — including an option to have Claude generate the system prompt for you. Custom subagents are stored as Markdown files with a YAML frontmatter header. You can also create them by hand.

Project-scoped subagents live in .claude/agents/ and can be checked into version control so your whole team shares them. User-scoped subagents live in ~/.claude/agents/ and are available across all your projects.

markdown

---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. Analyze code and provide actionable feedback
on quality, security, and best practices. Run git diff first to see
recent changes, then review modified files.

The two required fields are name (lowercase letters and hyphens) and description. The description is what Claude reads to decide when to delegate to this subagent, so write it clearly. The tools field is an allowlist — omit it to inherit all tools from the main conversation. The model field accepts sonnet, opus, haiku, fable, or inherit (the default).

Restart required for manual file edits

If you add or edit a subagent file directly on disk, you need to restart your Claude Code session before it loads. Subagents created through the /agents interface take effect immediately without a restart.

Run agents in parallel

You can ask Claude to research several independent areas at the same time. Claude runs the subagents in the background concurrently, then synthesizes their results once they finish.

text

Research the authentication, database, and API modules in parallel using separate subagents

Background subagents auto-deny any permission prompt that would normally require your input, so they can run unattended. If a subagent fails because it needed a permission it did not have, you can re-run the same task in the foreground to handle the prompts interactively. You can also @-mention a specific subagent by name to guarantee it handles a task: type @ and pick the agent from the typeahead, the same way you reference files.

Parallel results consume main context

When background subagents complete, their summaries return to your main conversation. Running many in parallel that each return detailed results can still consume significant context. For very large jobs, consider dynamic workflows instead.

Subagents vs other approaches

Claude Code has four ways to parallelize work. Choose based on who coordinates the work and whether tasks need to communicate.

Subagents — best when a side task would flood your main conversation. Claude delegates and collects results inside one session.
Agent view (claude agents) — best when you have several independent tasks you want to hand off and check on later from a single overview screen.
Agent teams — best when you want Claude to plan a project, split it into pieces, and supervise a group of workers. Experimental and disabled by default.
Dynamic workflows — best when a job is too large for a handful of subagents, or when you need findings cross-checked against each other (audits, large migrations, multi-angle research).

Key takeaways

Subagents keep your main conversation focused by doing noisy work in an isolated context. Use the /agents command to create custom ones — define a name, description, and optional tools list, and Claude will know when to call them. Store project subagents in .claude/agents/ and commit them so your team can share them. For everything beyond a handful of subagents, see the full parallelism guide at code.claude.com/docs/en/sub-agents.