Claude Code Subagents

What it does

• Each subagent runs in its own context window with a custom system prompt, specific tool access and independent permissions — only the summary returns to the main thread
• Automatic delegation by description: Claude reads each subagent's description to decide when to hand work over; combined non-built-in descriptions over 15,000 tokens trigger a startup warning
• Create via /agents — Claude drafts the subagent file (name, description, tools, model, system prompt) into ~/.claude/agents/ for you to review before first use
• Documented patterns for explicit invocation, foreground vs background runs, subagents spawning their own subagents, output scanning, and a concurrent-subagent limit
• Scope guide: subagents stay within one session — the page routes parallel independent sessions to background agents, message-passing to cross-session messaging, and supervised teams to agent teams

When to use it

High-volume side work that would flood the main conversation — research sweeps, log triage, file-heavy exploration — and any worker you keep re-spawning with the same instructions. Routing narrow tasks to a faster model like Haiku is also the documented cost-control lever.

Getting started

No install — it is a documentation page. In an interactive Claude Code session run /agents and describe the subagent you want and where to save it; Claude writes the file, and you review the frontmatter (name, description, tools, model) before first use.

Things to know

A subagent's requests count toward the same usage limits as your main conversation, and its description itself consumes context — keep descriptions short and push detail into the system prompt. Subagents are single-session: for many independent sessions in parallel you need background agents, and for coordinated teams, agent teams.