Subagents: How They Work in Claude Code, Cursor, Codex, and VS Code

What Is a Subagent?

A subagent is a secondary agent that a primary agent delegates a task to. It runs in its own context window, with its own system prompt and its own tool list, does the work, and returns only its result. The parent never sees the intermediate steps.

That last sentence is the whole idea. A search across a large repository might read 40 files to find the 2 that matter. Run inline, all 40 stay in the conversation for the rest of the session. Run in a subagent, the parent gets two file paths and a summary, and the other 38 are discarded with the subagent.

Three properties define the primitive, and all four major coding tools implement all three:

• Isolated context. The subagent starts fresh and its working context is thrown away on return. Nothing it read enters the parent's context except what it chose to report.
• Restricted tools. The subagent gets a narrower tool list than its parent. A search subagent that can read but not write cannot damage the repository, regardless of what it concludes.
• Bounded lifetime. One task, one result, then it terminates. VS Code states this outright: "Each subagent invocation is stateless. The main agent can't send follow-up messages to the same subagent."

A subagent is not a separate process, a separate session, or a separate model by necessity. It is a scoped call that happens to be made by a language model instead of a function. The parent asks for a result and gets a result.

Why Subagents Exist

Agents got long-running before context windows got useful. A coding agent working a real task spends most of its turns finding things, and every one of those turns writes into the same context the model has to reason over later. Cognition measured this directly while building their search model: their agent trajectories were often spending more than 60 percent of the first turn just retrieving context.

Expanding the context window does not fix it. A model with a million tokens of room still has to attend across everything in that room, and the signal-to-noise ratio of a context full of rejected grep results is bad in a way that more room makes worse. The fix is to not put the rejected results there in the first place.

The lead agent in that system was not smarter than the single agent. It was the same model. What changed is that the exploration happened somewhere else, and the lead agent's context stayed clean enough to plan over.

The cost side is real and worth stating flat. Anthropic reported that multi-agent systems use roughly 15 times more tokens than chat interactions. Subagents do not save tokens. They move tokens from an expensive context to a cheap one, which is a different and better property: the main model never pays to read the 38 files that did not matter.

For the retrieval half of this problem specifically, see agentic search and context engineering.

Subagents Across the Four Tools

Claude Code, Cursor, Codex, and VS Code all ship subagents, and the designs converged more than they diverged. The differences are in file format, in whether a subagent can spawn its own subagents, and in how much the user can invoke one directly.

Claude Code Subagents

Claude Code subagents are Markdown files with YAML frontmatter. Put one in .claude/agents/ to scope it to a project, or ~/.claude/agents/ to make it available in every project on your machine. Both directories are scanned recursively, and identity comes only from the name field, so the subdirectory layout is yours to organize.

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

You are a strict code reviewer. Report only correctness
issues and their file:line locations.

Only name and description are required. The description is what Claude reads to decide when to delegate, so it is a routing instruction, not documentation. The Markdown body becomes the system prompt: the docs note that subagents receive only this prompt plus basic environment details like the working directory, not the full Claude Code system prompt.

The frontmatter fields worth knowing

• tools and disallowedTools scope what the subagent can call. Omit tools and it inherits everything available to subagents.
• model takes an alias (sonnet, opus, haiku, fable), a full model ID, or inherit, which is the default. Routing a search subagent to a cheaper model is the main cost lever.
• isolation: worktree runs the subagent in a temporary git worktree, giving it an isolated copy of the repository, cleaned up automatically if it makes no changes.
• maxTurns caps agentic turns, which is the practical guard against a subagent that will not stop searching.
• background, memory, effort, skills, mcpServers, hooks, permissionMode, and color round out the list.

Invocation goes through the Agent tool, which was called Task before v2.1.63; existing Task(...) references still work as aliases. A subagent can spawn its own subagents by listing Agent in its tools, optionally narrowed to specific types with Agent(worker, researcher).

Related: skills, MCP, and plugins in Claude Code, and Claude Code hooks, which can be scoped to a single subagent through the hooks frontmatter field.

Cursor Subagents

Cursor documents subagents as "specialized AI assistants that Cursor's agent can delegate tasks to," each operating in its own context window and returning its result to the parent agent. Custom subagents live in .cursor/agents/ for a project and ~/.cursor/agents/ for a user, and Cursor also reads .claude/agents/ and .codex/agents/, so a repo with subagents defined for one tool works in the others without duplication.

The configuration surface is deliberately small: name, description, model (default inherit), readonly (default false), and is_background (default false). Three subagents ship built in: Explore searches and analyzes codebases, Bash runs series of shell commands, and Browser controls a browser via MCP tools.

Execution mode is the decision that matters. Foreground blocks until the subagent completes and returns the result immediately, which is right when the next step depends on it. Background returns immediately and lets the subagent work independently, which is right for long jobs and parallel streams. Since Cursor 2.5, subagents can launch child subagents.

Codex Subagents

Codex defines a subagent as "a delegated agent that Codex starts to handle a specific task," and an agent thread as "the thread where a subagent does its work." Supported clients let you open those threads to inspect progress, and /agent switches between them while they run.

Three agents are built in: default is the general-purpose fallback, worker is execution-focused for implementation and fixes, and explorer is the read-heavy codebase exploration agent. That split is the delegation pattern encoded as defaults, and it maps to what agents actually spend turns on.

Custom agents are standalone TOML files in ~/.codex/agents/ or .codex/agents/. Each must define name, description, and developer_instructions.

name = "reviewer"
description = "Reviews diffs for correctness before a PR opens"
developer_instructions = """
Read the diff. Report correctness bugs with file:line.
Do not comment on style.
"""

Parallelism is configured globally rather than per agent: agents.enabled turns the multi-agent tools on, agents.max_concurrent_threads_per_session caps concurrent threads, and agents.default_subagent_model and agents.default_subagent_reasoning_effort set defaults for spawned agents. When many agents are running, Codex waits until all requested results are available, then returns a consolidated response.

More on this pattern: Codex multi-agent workflows.

VS Code Subagents

VS Code has no separate subagent type. A subagent is a custom agent, defined in an .agent.md file, that another agent invokes. Two frontmatter fields control which side of that line an agent sits on. user-invocable: false keeps the agent out of the agents dropdown in chat, creating an agent that is only accessible as a subagent. disable-model-invocation: true does the reverse, preventing the agent from being invoked as a subagent by other agents.

Invocation is agent-initiated rather than user-driven. The main agent needs the agent/runSubagent tool enabled, and the agents field on the parent restricts which subagents it may invoke: a list of names, * for all, or [] for none.

Two constraints are worth planning around. Each subagent invocation is stateless, so the main agent cannot send follow-up messages to the same subagent: whatever the parent needs must be in the initial task. And the requested model cannot exceed the cost tier of the main model, so a cheap parent cannot delegate upward to an expensive child. Subagents cannot invoke further subagents by default; enabling chat.subagents.allowInvocationsFromSubagents permits nesting up to 5 levels.

Subagent Orchestration Patterns

Three patterns account for nearly all production subagent use. They differ in how results flow back, and that determines the cost profile.

Rules that hold across all three

• Fan out on independence, not on size. Two subagents editing the same file serialize on merge conflicts and cost more than doing the work inline. Cursor's parallel-agent workflow gives each agent its own git worktree for exactly this reason, and Claude Code offers the same through isolation: worktree.
• The return value is the design. A subagent returns a summary, and everything it saw but did not report is gone. Specify the output format in the system prompt: file paths and line ranges, not prose about what it looked at.
• Restrict tools by default. A subagent that only needs to read should not be able to write. Cursor has readonly, Claude Code has tools and disallowedTools, VS Code has per-agent tool lists.
• Cap the turns. Without maxTurns or its equivalent, an unproductive search subagent burns its whole budget before reporting failure.
• Do not use a subagent for a short task. Spawn overhead and the summarization round trip cost more than the work.

Specialized Models for Subagents

A subagent runs one kind of task repeatedly. That is the condition under which a specialized model beats a frontier model, and it is why the 15x token multiplier is survivable: the multiplier applies to the cheap contexts.

Three workloads dominate subagent traffic, and Morph builds a model for each.

The pattern is the same in all three cases. Take the loop the parent agent runs most, and make it a model that does only that. WarpGrep replaces the exploration turns that Cognition measured at more than 60 percent of the first turn. Fast Apply replaces full-file rewrites. Compact replaces the compaction pause.

FAQ

What is a subagent?

A subagent is a secondary agent that a primary agent delegates a task to. It runs in its own context window, with its own system prompt and its own tool list, performs the task independently, and returns only its result to the parent. The parent never sees the intermediate steps. This keeps exploration output out of the main conversation, which is why every major coding tool now ships subagents.

What is the difference between an agent and a subagent?

An agent owns the conversation with the user and decides what to do next. A subagent is spawned by that agent to handle one bounded task and then terminates. The structural difference is context: the agent accumulates the full session history, while a subagent starts with only its system prompt plus the task it was handed, and its working context is discarded when it returns. A subagent also usually has a narrower tool list than its parent.

How do I create a subagent in Claude Code?

Create a Markdown file with YAML frontmatter in .claude/agents/ for a project-scoped subagent, or ~/.claude/agents/ for one available everywhere. Only name and description are required; tools, model, maxTurns, isolation, and the rest are optional. The Markdown body becomes the system prompt. Claude Code watches both directories and picks up edits within a few seconds without a restart.

Do subagents have their own context window?

Yes, in all four implementations. Claude Code documents that each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. Cursor documents that each subagent operates in its own context window. VS Code documents that each subagent invocation is stateless and the main agent cannot send follow-up messages to the same subagent. Codex runs each subagent in its own agent thread.

Can subagents run in parallel?

Yes. Codex spawns agents in parallel and waits until all requested results are available before returning a consolidated response, capped by agents.max_concurrent_threads_per_session. Cursor offers foreground mode (blocks until complete) and background mode (returns immediately). Claude Code runs subagents in the background by default as of v2.1.198. VS Code permits nesting up to 5 levels when chat.subagents.allowInvocationsFromSubagents is enabled.

Do subagents cost more tokens?

In aggregate, yes. Anthropic reported that multi-agent systems use roughly 15 times more tokens than chat interactions. The trade is that those tokens are spent in cheap, disposable contexts rather than the expensive main one, and the main model never pays to read the exploration output. Routing subagent work to a smaller or specialized model is the standard way to make the economics work.

When should you not use a subagent?

When the parent needs the intermediate reasoning rather than just the answer. Subagents return a summary, so anything seen but not reported is gone. If the task needs back-and-forth, a subagent is the wrong primitive: VS Code makes this explicit by documenting that each invocation is stateless. Short tasks are also a bad fit, because spawn overhead exceeds the work.

Can a subagent spawn its own subagents?

In Claude Code, yes: list Agent in the subagent's tools, optionally narrowed with Agent(worker, researcher). In Cursor, yes since version 2.5. In VS Code, not by default, but enabling chat.subagents.allowInvocationsFromSubagents allows nesting up to 5 levels. In Codex, concurrency is bounded by agents.max_concurrent_threads_per_session rather than a depth limit.