Subagent: A Helper With Its Own Context

A subagent is a specialised AI helper that a main agent hands a task to. It runs in its own context window with its own system prompt, tool access and permissions, does the work, and returns a short summary instead of the whole trail. The main conversation stays small. This page uses Claude Code's definitions, checked 31 October 2026.

At a glance

What it is

Claude Code's glossary defines it as a specialised AI assistant that runs in its own context window with a custom system prompt, specific tool access and independent permissions. It works on a delegated task and returns a summary to the main conversation. A subagent stays inside the session that spawned it.

The docs say to use one when a side task would flood your main conversation with search results, logs or file contents you will not reference again. The subagent does that work in its own context and returns only the summary. You define a custom one when you keep spawning the same kind of worker with the same instructions.

The reasons to use subagents, in the docs' own list:

• Preserve context. Exploration and implementation stay out of your main chat.
• Enforce constraints. Limit which tools a subagent can use.
• Reuse configurations. User-level subagents work across projects.
• Specialise behaviour. Focused prompts for one domain.
• Control costs. Route tasks to faster, cheaper models such as Haiku.

Why context matters here

A model can only hold so much text at once, its context window. Every file read and command output lands in it. Claude Code's context explainer shows a subagent handling research in its own window so that large file reads stay out of the main one: only the summary and a small metadata trailer come back. After a long session fills the window, the main conversation is compacted, which loses detail. Delegating the noisy part avoids some of that loss.

Built-in subagents

Explore and Plan start without your CLAUDE.md files and the git status snapshot, to keep research fast and cheap. Other built-in and custom subagents load both, unless a custom one sets omitClaudeMd. When Claude calls Explore it states a thoroughness level: quick, medium or very thorough. The docs note that you can override Explore with your own subagent of the same name, for example one set to a lower-cost model.

What a subagent file looks like

A custom subagent is a markdown file with frontmatter. The docs' own example is a code improver:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
---

You review code and suggest improvements. Do not edit files.
List each issue with the file, the line and a one-line fix.

The file lives in ~/.claude/agents/ for all your projects or .claude/agents/ for one project, where it can be committed so a team shares it. Claude Code watches both folders and picks up changes within seconds, with one exception: if ~/.claude/agents/ did not exist before the session started, restart.

The frontmatter fields the docs list include description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, memory, effort and background. The description matters most, because Claude uses it to decide when to delegate. Descriptions take up context, so keep them short: the docs say a warning appears at startup when the combined descriptions of your non-built-in subagents exceed 15,000 tokens.

Scope and precedence

Project subagents are found by walking up from the working directory. Keep names unique: if two files under one .claude/agents/ tree use the same name, only one loads, chosen by filesystem order.

Subagent, skill, agent team: which one

A subagent is a worker; a skill is a method. A skill can even tell a subagent how to do something. For a longer comparison see subagents vs skills. A subagent also differs from an agent talking to a remote agent over A2A: the first lives inside your session, the second crosses a network boundary.

Costs and trade-offs

Subagents save context, not tokens. The docs say each one sends its own requests, which count toward the same usage limits as your main conversation. Three subagents exploring in parallel use more total tokens than one agent reading the same files, in return for a cleaner main context and faster wall-clock time. Use them when the output you would keep out of the main chat is large, and avoid them for a three-line lookup.

Other trade-offs:

• Less shared context. A subagent does not see the whole conversation, so the delegation message must include what it needs.
• Summaries lose detail. If the main agent needs an exact line, ask for it in the summary.
• Permissions are separate. A subagent can be given narrower tools than the main agent, which is a feature, and can also block work you expected it to do.
• More moving parts. Debugging a chain of helpers is harder than debugging one agent.

A worked delegation (example)

Say you ask the main agent, "Why does the checkout test fail?" Without a subagent, the main agent reads the test, the three files it imports, a 4,000-line log and two config files. All of that now sits in your context. With a subagent, the main agent writes one message: "Find why the checkout test fails. Return the cause, the file and line, and the smallest fix. Do not edit." The subagent reads everything in its own window, and a ten-line summary comes back. Your main window grew by ten lines instead of thousands. The price is that the subagent's reading still used tokens, and if its summary is wrong, the main agent inherits the mistake, so ask for file and line references you can check.

Good uses

Browse more at subagents, and build your own with how to write a subagent.

Our take

Subagents are the simplest answer to a real limit: a model's working memory fills up. Use the built-in ones first, write a custom one when you repeat the same delegation, keep tools narrow and descriptions short. Expect extra token use, not less. We describe them from Claude Code's documentation, and other agents implement the idea with their own names and rules. We have not tested the examples here. For the standing instructions a subagent inherits, see CLAUDE.md.