What is Subagent?
A specialized agent spawned by a parent agent to handle a focused subtask with its own context window. Common pattern for long-running work: the parent orchestrates, subagents do focused reads/writes without bloating the parent's context.
What it is
A subagent is a specialised assistant that a main agent delegates a task to. In Claude Code it runs in its own context window with its own system prompt, tool access and permissions, does the work there, and returns only a summary, so verbose search results, logs or file contents do not fill the main conversation.
Why use one
Claude Code's documentation lists the reasons: preserve context by keeping exploration out of the main thread, enforce constraints by limiting which tools it can use, reuse configurations across projects, specialise behaviour with a focused prompt, and control cost by routing work to a cheaper, faster model.
How one is defined
A subagent is a Markdown file with YAML frontmatter; name and description are required, the description tells Claude when to delegate, and the Markdown body becomes the system prompt. Optional fields include tools, model and permissionMode. Project subagents live in .claude/agents/ and personal ones in ~/.claude/agents/. By default a subagent can spawn its own subagents up to three layers deep; omit the Agent tool from its tools list to stop that.
Example
A read-only "code-reviewer" subagent is given only the Read, Glob and Grep tools. The main agent hands it a diff, it reads files in its own context window, and only its findings come back.
Sources
See also
← Back to the full AI agent glossary.