Jonathon's AI Wiki

Claude Code Subagents

4 min read

Source: ai-research (web research, 2026-04-11) Type: Product Feature Product: Claude Code

Subagents are isolated Claude instances spawned by a main session to handle specific tasks independently. Each subagent gets its own context window, custom system prompt, and scoped tool access. They run in parallel, return only their summary/results, and keep the main context window clean. This is the workhorse pattern for scaling Claude Code work.

How subagents work

  • The main session spawns one or more subagents, each with a defined task
  • Each subagent gets its own context window — isolated from the parent and from each other
  • Subagents can have different permissions: read-only, research-only, or full editing access
  • Custom system prompts scope each subagent to its specific task
  • Results flow back to the parent session as summaries — raw context is discarded
  • Multiple subagents run in parallel for throughput

Subagent types

  • Read-only — reviewers, auditors, code analysis. Cannot modify files.
  • Research — gather information, search codebases, read documentation. Read access only.
  • Code writers — create files, execute code, make changes. Full editing permissions.

Defining reusable agents

  • Store agent definitions in .claude/agents/ for project-level shared specialists
  • These become reusable across sessions and team members
  • Each definition specifies the system prompt, tool access, and permissions

Nested subagents — depth up to 5 (2026-06-09)

[X signal — @bcherny, Claude Code creator, ~2026-06-09] Claude Code added nested subagents: a subagent can now itself spawn further subagents, instead of the prior single-level main→subagent fan-out. Deep work can decompose hierarchically — a research subagent delegates its own sub-investigations, each layer keeping its context isolated.

  • Depth cap = 5. Nesting is initially capped at five levels; Anthropic is experimenting with deeper hierarchical agents.
  • Why it matters: better context management for large tasks — each level offloads to fresh isolated contexts rather than one orchestrator holding the whole tree. Complements dynamic workflows (which orchestrate hundreds of parallel subagents from a written script) by letting any agent in the tree branch on its own.
  • First-party post from Claude Code’s creator; the exact shipping version is unconfirmed (announced alongside the ~June 9 release wave — see W25). ^[inferred — depth/version detail from a single X post; confirm against the changelog]

Key Takeaways

  • Nested subagents (2026-06-09): subagents can now spawn subagents, capped at depth 5 — hierarchical decomposition with per-level context isolation
  • Subagents keep the main context window clean by offloading work to isolated instances
  • Different permission levels (read-only, research, code writer) control what each subagent can do
  • Parallel execution means 3 subagents finish roughly 3x faster than sequential work
  • Reusable agent definitions in .claude/agents/ create project-level specialists
  • Subagents do NOT communicate with each other — use Agent Teams when peer coordination is needed
  • Custom system prompts + scoped tool access = precise control over each subagent’s behavior

Try It

  1. In Claude Code, ask for a task that benefits from parallelism (e.g., “Audit the security of the auth module while simultaneously writing tests for the payments module”)
  2. Observe how Claude Code spawns subagents with appropriate permissions
  3. Create a reusable agent: add a YAML file to .claude/agents/ with a specialist definition (e.g., security-reviewer.yml with read-only permissions and a security-focused system prompt)
  4. Use subagents liberally for research tasks — “have a subagent investigate how the caching layer works while I continue implementing the feature”

Open Questions

  • What is the maximum number of concurrent subagents before performance degrades?
  • How much context can a subagent return before the parent session’s context window is impacted?
  • Can subagent definitions in .claude/agents/ reference MCP servers or skills?

Graph View

Backlinks