Subagents: delegate work to isolated agents

A subagent is a second Claude that does one job in its own context window and hands back only the result. Delegate the test run that prints 4,000 lines, the search across 300 files, or the review that should not see your reasoning, and your main conversation stays short enough to keep working in.

Each subagent runs in its own context window with its own system prompt, tool access, permissions and model. Claude hands it a task message, it works with its tools, and only its final message returns to the conversation that started it. Everything it read along the way stays in its own context.

Claude Code ships with built-in subagents:

• Explore is a fast, read-only agent for searching and understanding a codebase. Claude asks it for a thoroughness level: quick, medium or very thorough.
• Plan researches the codebase while you are in plan mode, so exploration output stays out of the read-only main conversation.
• general-purpose has every tool available to subagents, for tasks that need both exploration and changes.

Explore and Plan skip your CLAUDE.md files and the git status snapshot to stay fast. You add your own subagents as Markdown files with YAML frontmatter in .claude/agents/ for a project or ~/.claude/agents/ for yourself. The frontmatter sets the name, the description Claude uses to decide when to delegate, the tools and the model. The body is the system prompt.

Codex, Cursor, GitHub Copilot and Gemini CLI document subagent or custom agent features of their own, with different file formats. This page covers Claude Code and the Claude Agent SDK.

Delegate when one of five things is true.

• The output is noisy. Test runs, log analysis, documentation fetches and wide searches produce text you will not read again. The subagent reads it and returns a summary.
• The work splits into independent parts. Research the auth, billing and search modules at the same time, and wait for the slowest instead of the sum.
• A fresh view helps. A reviewer that has not seen your reasoning judges the diff on its own terms.
• The tools should be narrower. A read-only reviewer cannot edit, and a database agent can run only validated queries.
• A cheaper model will do. Route simple lookups to Haiku while the main conversation stays on a stronger model.

Keep the work in the main conversation when the task needs back-and-forth, when planning, implementing and testing share a lot of context, when the change is small, or when latency matters: a subagent starts fresh and spends time gathering context. For a quick question about something already in your conversation, use /btw, which sees your context and adds nothing to history. When the side task needs the whole conversation, fork it with /subtask (v2.1.212 and later) instead of re-explaining. For a reusable procedure that should run in the main context, write a skill.

Claude delegates on its own when a task matches a subagent's description, and phrases such as "use proactively" in the description encourage it. You can also ask by name, @-mention the agent to guarantee it runs, or start a whole session as that agent with claude --agent <name>.

A subagent that is not a fork starts with:

1. Its own system prompt, from the file body, plus environment details. Not Claude Code's system prompt.
2. The task message Claude writes when it delegates.
3. Your CLAUDE.md files and project rules, unless it is Explore, Plan, or a definition with omitClaudeMd: true.
4. A git status snapshot, again except for Explore and Plan.
5. The full text of any skills listed in its skills field.

It does not see your conversation history, the files Claude already read, your output style or your auto memory. If a rule must reach it, put the rule in the agent's prompt or in the delegation.

Subagents run in the foreground, blocking until they finish, or in the background while you keep working. In interactive sessions on v2.1.232 and later, fork mode is on by default and the subagents Claude spawns run in the background. A subagent can spawn its own subagents up to three layers deep, and a session runs at most 20 at once. Claude Code scans each subagent's final report before Claude reads it and marks text that imitates system messages or mentions permission settings, because a subagent may have read files or web pages carrying planted instructions.