Claude Code subagents are scoped worker agents that Claude Code spawns inside a session: each gets its own context window, a task prompt, and a restricted tool set, then returns its result to the main agent. They parallelize research, review, and implementation work without polluting the primary context that the main agent is reasoning in.
Subagents are the first taste of multi-agent work most Claude Code users get — and the place where the limits of single-session orchestration first show up. This guide covers how they work, where they shine, and what to reach for when you outgrow them.
What Claude Code subagents actually are
When Claude Code dispatches a subagent, it hands a task description to a fresh agent instance. That instance starts with a clean context window: it does not see your conversation history, only the prompt it was given and whatever it reads itself. It works with the tools it is allowed to use, finishes, and reports back a final message that the main agent consumes as a tool result.
You can also define custom subagents — specialized personas with their own system prompt and tool restrictions, stored as markdown files in your project. A review subagent might get read-only tools; a migration subagent might get write access to a single directory. The restriction is the point: a subagent that can only read cannot wreck anything.
When subagents help (and when they don't)
Subagents earn their keep on fan-out work. Searching a large codebase for every usage of a pattern, reviewing a diff from several angles at once, or implementing three independent fixes in parallel — each of these is self-contained, benefits from a clean context, and produces a compact result. The main agent stays focused while the heavy reading happens elsewhere.
They are the wrong tool when the task needs shared memory. A subagent does not know what you discussed twenty minutes ago, what the last subagent concluded, or why a decision was made. Tasks that depend on accumulated session knowledge — long debugging hunts, design discussions, anything with subtle context — degrade badly when delegated, because the prompt can never carry everything that matters.
The ceiling: subagents share one brain
Every subagent in a session works on the same checkout, under the same supervisor, with results flowing back to one context. That model breaks at exactly the point where modern AI development gets interesting: when more than one independent agent — or more than one person running agents — touches the same application.
A subagent in your Claude Code session cannot see that a Cursor agent on a teammate's machine just renamed an endpoint. It cannot claim a piece of work so the Codex session next door does not duplicate it. It cannot record what it shipped so the next session knows. Subagents parallelize within a session; they do nothing across sessions, tools, or people.
Beyond one session: coordinating Claude Code with other agents
Cross-session coordination needs shared state that outlives any one agent: who is working on what, what the API contract actually is, what changed since yesterday. That is an agent orchestration problem, and the practical answer is a shared MCP server rather than a bigger session.
AppHandoff is a hosted MCP server at https://api.apphandoff.com/api/mcp-bot that gives every connected agent — Claude Code and its subagents, Cursor, Codex — the same grounded view: scanned API contracts, database schema, frontend/backend mismatch detection, and handoff tickets with role assignments. An agent calls get_my_workload to see what is open for its role instead of guessing; it files what it cannot finish with report_handoff_request so the work is visible to every other agent. The full setup for a mixed-agent team is covered in multi-agent orchestration with Claude Code, Cursor, and Codex.
A practical rule of thumb: subagents for parallelism inside a task, a shared MCP server for coordination across tasks, tools, and people. The two compose — your subagents can call the same MCP tools the main agent uses, so even delegated work stays grounded in real project state. If you are picking which servers to connect first, start with the best MCP servers for Claude Code.