Subagents in Claude Code

Context

A subagent in Claude Code is a specialized assistant that runs a task in its own context —with its own system prompt, tools, and permissions— and returns only the result to the main conversation. It's useful when a side task (exploring the codebase, reviewing a diff) would flood your context with files and logs you'll never look at again.

Watch out for a common misconception: a subagent isolates context within a single session; it isn't "parallelism" by itself. To truly run many sessions in parallel, Claude Code has background agents and agent teams. The subagent is, above all, a context-management tool.

Setup

• Ad-hoc: ask for it explicitly — "use a subagent to investigate how token refresh works."
• Reusable: define a subagent in .claude/agents/<name>.md with frontmatter (name, description, tools, model) and a focused system prompt. Claude delegates based on the description.

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review for: injection (SQL, XSS),
authz, hardcoded secrets, and insecure data handling. Give line and fix.

State as of July 2026. The location (.claude/agents/) and frontmatter format may change.

Examples

Two high-value uses:

1. Investigation without cluttering context:
   "Use subagents to investigate how we handle auth state and whether we
    already have OAuth utilities to reuse."
   → the subagent reads 20 files in its context and returns 1 summary.
 
2. Review with fresh eyes:
   "Use a subagent to review this diff for edge cases."
   → a fresh model judges the result without the bias of having written it.

The natural case in the course (testing): one subagent per domain function, each generating its tests in its own context, without contaminating each other.

Particularities

• Advantage: you preserve context (the exploration lives in another window) and can limit which tools each subagent uses.
• Advantage: the reviewer-as-subagent doesn't carry the bias of whoever wrote the code.
• Key nuance: it isn't parallelism across sessions — that's background agents / agent teams. The subagent works inside your session.
• When NOT to: tasks that need tight coordination with each other or share complex fixtures; there a sequence in the main session is simpler.