What is a subagent?
A subagent is a separate AI agent that a coding agent starts to handle one task, such as searching a codebase or reviewing a diff. It runs with its own context window, its own system prompt and often a narrower set of tools, then returns a summary. The main agent keeps its context for decisions instead of raw output.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
The main agent decides a task is worth delegating: it matches your request against each subagent's description, or you name one in the prompt.
It writes a brief. The subagent starts with a fresh context, so that brief is everything it knows about your conversation.
The subagent runs with its own system prompt, tool list and permissions, either blocking the main agent or in the background.
It returns a report. Only the report enters the main agent's context, not the files it read or the commands it ran.
The main agent carries on. In Claude Code it can message the same subagent again to continue where it left off.
Source: Claude Code docs: subagents
Subagents versus one long conversation
Every file an agent reads and every command it runs lands in its context window. A codebase search that touches forty files can use up more of that window than the feature you asked for. A subagent takes the search somewhere else. It reads the forty files in its own context and hands back three paragraphs. Your conversation stays about the decision, not the evidence.
The cost is a hand-off. The subagent doesn't know what you discussed, so the main agent has to write a brief, and the brief and the report both lose detail. Requests a subagent makes count towards the same usage limits as your main conversation, so it is a trade of context for tokens, not a saving.
Example: a code reviewer in Claude Code
In Claude Code a subagent is a Markdown file in .claude/agents/ for one project or ~/.claude/agents/ for all of them. The frontmatter needs only a name and a description; the body becomes the subagent's system prompt.
---
name: code-reviewer
description: Reviews a diff for correctness and style. Use after a change is made.
tools: Read, Glob, Grep
model: sonnet
---
You review code. Report concrete problems with file and line, most serious first.
The tools line is an allowlist, so this reviewer can read but not edit. model lets a cheap task run on a cheaper model. Claude delegates on its own when your request matches the description, or you ask for it by name. Claude Code also ships built-in subagents: Explore for read-only search, Plan for research during plan mode, and a general-purpose one with every tool.
Each invocation is a new instance. To pick up earlier work, ask Claude to resume the subagent; a resumed one keeps its full history. Explore and Plan are one-shot and cannot be resumed.
Subagents in Codex and Cursor
Codex defines custom agents as TOML files in ~/.codex/agents/ or .codex/agents/, with name, description and developer_instructions required. Its built-ins are default, worker and explorer, and /subagents switches between the running threads. Codex's docs recommend starting with parallel read-heavy work, because several agents editing code at once can produce conflicts.
Cursor reads Markdown subagents from .cursor/agents/ or ~/.cursor/agents/, and for compatibility also from .claude/agents/ and .codex/agents/. It adds a readonly flag and an is_background flag, ships Explore and Browser built-ins, and runs a subagent when you type /name in a prompt.
Common mistakes
- Delegating a two-file lookup. If you could do it in three tool calls, the brief and the report cost more than the work.
- A vague brief. The subagent has no memory of your conversation. Say what to find, what you already ruled out, and which files to start from.
- Running the task yourself as well. Once delegated, wait for the report; doing both wastes the tokens and can produce conflicting edits.
- Trusting the report as fact. It comes back in the same confident tone whether the subagent found the answer or guessed. Spot-check anything you will act on.
- Letting descriptions sprawl. Claude Code loads every subagent description into context on each turn and warns when they exceed 15,000 tokens together.
FAQ
- Do Claude Code subagents see my conversation?
- No. Each one starts with a fresh context: its own system prompt, the brief the main agent wrote, your CLAUDE.md files and a snapshot of git status. Anything else it needs has to be in the brief. The built-in Explore and Plan subagents skip CLAUDE.md as well.
- Can a subagent start its own subagents?
- In Claude Code, yes, up to three layers below the main conversation by default, and up to 20 subagents can run at once in a session. Both limits are settings you can change, and setting the depth to one turns nesting off.
- What is the difference between a subagent and a multi-agent system?
- A subagent is one agent working for another and reporting back; the main agent stays in charge. A multi-agent system is the general term for several agents cooperating, which may include peers that hand work to each other with no single owner.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.