A subagent runs a focused task in its own context window and reports back a summary, keeping the main session's context clean instead of diluted by exploratory work that isn't relevant afterward.
1A Subagent Has Its Own Context Window
Unlike a custom command, which runs inline in the current session, a subagent is launched as a separate instance with a specific task. It does its own reading and reasoning in isolation, and only its final report comes back into the main session — the exploratory detail never dilutes the main context.
2Delegate Broad, Isolable Side Tasks — Not Small Inline Edits
A subagent earns its overhead on tasks whose exploration is extensive and whose intermediate detail wouldn't be useful in the main session afterward — a security audit, a broad codebase search, a research question. A one-line edit related to the current task doesn't need this isolation.
3Step-by-Step Breakdown
A Focused Sub-Task Inside a Bigger One. While building the export feature, you also want a security review of the new /api/export route — checking for injection or path issues. Doing that research inline would pull a lot of exploratory reading into your main session's context, most of it irrelevant afterward.
A Subagent Runs in Its Own Context. A subagent is a separate Claude Code instance, launched with a focused task and its own context window, that reports back only a summary. All the exploratory reading it does to review the route stays isolated — your main session's context keeps working on the export feature, undiluted.
Why does running the security review as a subagent, rather than inline in the main session, help keep the main session focused on building the export feature?
- →The subagent's exploratory reading happens in its own separate context window — only its final summary comes back, so the main session's context isn't diluted the way it would be with context rot from Module 2.
- →Subagents always complete tasks faster than the main session would.
Decide: Inline or Subagent?. Not every side task deserves its own subagent. Practice the judgment call on two different Fixly tasks.
Delegate the Exploration, Keep the Decision. The subagent explores and reports; you still decide what to do with its finding — here, fixing the unsanitized query param before shipping. Next lesson: hooks and MCP servers, for connecting Claude Code to tools and events outside the conversation entirely.
Level Up 🚀
Advanced cheat sheets, SEO tricks, and interview prep for this topic.
Browser Support
N/A — subagents run as CLI processes.
N/A — subagents run as CLI processes.
N/A — subagents run as CLI processes.
N/A — subagents run as CLI processes.
Accessibility (A11y)
1Read the Subagent's Full Report, Not Just Its Headline
A subagent's summary is written to be self-contained since its working context isn't visible afterward — reading it in full (not skimming for a pass/fail) is necessary to actually act on what it found.
SEO Implications
- 1
Target 'Claude Code subagents explained' and 'when to use a subagent' separately
Users search for what the feature is and for the judgment call of when it's actually worth using as distinct questions.
Best Practices
Delegate Tasks Whose Exploration Wouldn't Be Useful Afterward
The clearest signal a task belongs in a subagent: the reading and searching it requires is large relative to the task, and none of that intermediate detail matters once the task is done — only the conclusion does.
Frequent Bugs
Spinning up a subagent for a small, directly relevant edit, adding coordination overhead with no context-isolation benefit.
Reserve subagents for broad, exploratory side tasks. Keep small edits directly related to the current task inline in the main session.
Real-World Examples
The Isolated Security Audit
A security review of Fixly's new export route required reading several unrelated files to check for injection patterns — detail that had nothing to do with building the feature itself. Running it as a subagent kept that exploration out of the main session, which stayed focused on the export feature with only the audit's one finding folded back in.
// Main session context: stayed focused on the export feature
// Subagent's own context: absorbed the exploratory security reading