Subagent

In plain words

Ask a coding agent where authentication happens and it may open many files to find out. Without a subagent, every one of those reads lands in the conversation the agent is using to reason about your real task, and stays there. OpenAI's Codex documentation calls the result context rot: "performance degrades as the chat fills up with less relevant details."

A subagent moves that work somewhere else. The main agent hands the search to a helper with its own empty context window (the block of text a model can see on one request). The helper reads the files; the main agent gets back a paragraph. It works like a lead engineer asking a colleague to go and find out, instead of reading every file over their shoulder.

Two kinds of isolation are involved. Input isolation means the subagent starts without your conversation history, so the main agent has to put everything the helper needs into its prompt. Output isolation means the helper's tool calls and intermediate results never come back. The Claude Agent SDK docs put it plainly: "only its final message returns to the parent."

The word is not tied to one product. Claude Code, Codex, Gemini CLI, Cursor and VS Code all ship subagents, each with its own file format, so there is no shared spec the way there is for the Model Context Protocol. The loop that spawns and collects them is part of the AI harness around the model.

How it works

Every tool follows roughly the same five steps:

1. You write a definition. In Claude Code it is a Markdown file with YAML frontmatter in .claude/agents/ for one project or ~/.claude/agents/ for all of them. Only name and description are required, and a subagent with no tools field inherits every tool available to subagents. Codex uses TOML files in .codex/agents/.
2. The main agent sees each subagent's description. Gemini CLI exposes every subagent "as a tool of the same name"; Claude Code delegates through its Agent tool, which was called Task before version 2.1.63.
3. Delegation happens when the main agent matches a task to a description, or when you name the helper yourself, as with @codebase_investigator in Gemini CLI.
4. The subagent runs its own model-and-tool loop in its own context window, under its own permissions.
5. Its final message returns to the main agent as the result. Everything else it read stays behind.

This is the example definition from the Claude Code subagent docs:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

We saved it as .claude/agents/code-reviewer.md in a scratch repo and started Claude Code 2.1.319 in print mode with a dummy key and the API base URL pointed at a closed local port, so no model request could succeed. The session's init event (abridged below) already listed the new subagent beside the agents that were already available:

{"claude_code_version":"2.1.319",
 "agents":["claude","claude-code-guide","code-reviewer","Explore",
           "general-purpose","Plan","statusline-setup"]}

Two near-miss files did not load at all: one with a name but no description, and one with a blank line above the opening ---. Neither appeared in the list, and nothing warned us. The docs confirm it: Claude Code skips such files "without reporting it in the session". If a custom subagent is missing from the agent list, check its frontmatter. For a missing description, Claude Code writes the reason to the debug log, which you see by running with --debug.

Where the tools differ

Nesting and triggering are where implementations split, as of November 2026:

In Claude Code the depth limit is set with CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH; a value of 1 turns nesting off.

Why it matters

Claude Code ships a built-in Explore subagent for one context-heavy job, codebase search: "A fast, read-only agent optimized for searching and analyzing codebases", whose output stays out of your main conversation. For what fills an agent's context before you type anything, see how AGENTS.md, Skills and MCP split the context budget.

Isolation is not free. In Anthropic's data, multi-agent systems used about 15 times the tokens of a chat and single agents about 4 times. Anthropic still found that an Opus 4 lead agent with Sonnet 4 subagents beat single-agent Opus 4 by 90.2% on its internal research eval (Anthropic engineering). The same post notes that "most coding tasks involve fewer truly parallelizable tasks than research".

Read-heavy side tasks are where subagents pay off: codebase search, test logs, review passes with one concern each. Parallel edits are where they cause trouble, because helpers writing the same files at once conflict, a risk the Codex docs flag directly. A planner, coder, tester and reviewer chained in sequence is one middle ground; this guide builds that four-subagent pipeline in Claude Code.

Origin

Anthropic described its Research feature in June 2025 as "an orchestrator-worker pattern, where a lead agent coordinates the process while delegating to specialized subagents that operate in parallel." Claude Code 1.0.60, published on npm on 24 July 2025, added user-defined ones: "You can now create custom subagents for specialized tasks!" Codex, Gemini CLI, Cursor and VS Code now ship their own versions under the same name. The dynamic subagents Google announced at I/O 2026 follow the same pattern.

Common confusions