Subagent

What is a Subagent, and how does it differ from the main conversation handling a task directly?

A subagent is a separate, independently operating Claude instance that the main session spawns — it has its own System Prompt, its own tool list, and can even run on a different model than the main conversation. The main conversation only sees the subagent's final summary report; it never sees which files it read or what steps it tried along the way — that process is isolated inside the subagent's own Context Window and doesn't consume space in the main conversation.

The key difference from handling a task directly in the main conversation is context isolation. If a task runs directly in the main conversation, every step of the process (reading files, analyzing, fixing) stays fully in the conversation history, and over time this fills up the context. A subagent isolates that process, keeping the main conversation clean enough to support longer, multi-turn discussion without being drowned out by the execution details of a single task.

Why is a Subagent needed, and what problem does it solve?

Before subagents existed, complex tasks (reviewing a large PR, or a refactor requiring multiple steps) running directly in the main conversation created two concrete problems. First, as mentioned above, the context gets flooded with process detail. Second, tasks interfere with each other — trying to advance several unrelated pieces of work in the same conversation easily disrupts each other's thread, forcing the user to keep reminding Claude to "go back to what we were doing."

A subagent gives each task its own clean context space to run in, without interfering with anything else; background subagents go a step further, letting a subagent run concurrently alongside the main conversation so the user doesn't have to stop and wait for a task to finish. This shifts how Claude handles complex, multi-task workflows from "focus on one thing at a time" to "decompose work into parallel, isolated tracks that each move forward independently."

How does a Subagent actually work, and what execution modes does it support?

The most basic way to define a subagent is to place a Markdown file under .claude/agents/, using frontmatter to define its name, description, available tools, and model, with the body serving as that subagent's System Prompt. The main conversation (the lead agent) reads each defined subagent's description text and judges whether the current task is a good fit to hand off — a judgment process similar to how Claude decides whether to call a particular tool.

Execution splits into two modes: foreground and background. A foreground subagent blocks the main conversation — the user has to wait for it to finish before continuing, and if it hits an operation needing authorization along the way, the permission prompt passes straight through to the user. A background subagent runs concurrently with the main conversation; before launching, it asks what tool permissions it will need, and once approved and running, any operation beyond that authorized scope gets automatically denied without asking the user again. There's also nested spawning — a subagent can itself spawn another layer of subagents, currently supported up to a certain default depth to prevent runaway, uncontrolled layering.

What does a Subagent actually mean for me, and when should I proactively define my own?

If you find yourself repeatedly asking Claude to do the same highly self-contained type of work — like consistently "review code against the same standard" or "run a fixed security-check process" — defining that role as a named subagent means that from then on, whenever a task matches this description, the main conversation automatically judges whether to delegate it, without you needing to re-describe how that role should behave each time.

If you're just a regular Claude Code user who has never defined a subagent yourself, that doesn't mean you're not already benefiting from this mechanism — a built-in command like /code-review already defaults to running as a subagent (in background mode), so you're already getting the context-cleanliness this provides. The real moment worth noticing is when you find the same conversation getting messier because you're switching between different kinds of tasks, or when you want to advance several unrelated pieces of work at once — that's the signal it's worth splitting some of that work off into subagents.