Jonathon's AI Wiki

Claude Code Subagents

5 min read

Source: ai-research (web research, 2026-04-11); raw/x-account-bcherny-2071647677591466098.md (X post, 2026-06-29 — background-by-default default flip) 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]

Background execution by default (2026-06-29)

[X signal — @bcherny, Claude Code creator, 2026-06-29] In the next version of Claude Code, subagents will run in the background by default — you can keep conversing with the main Claude instance while a subagent works, instead of the session blocking until it returns. To force a specific subagent to run in the foreground, just instruct Claude to do so.

  • Rollout: the behavior had already been rolling out gradually to a subset of users before this default flip was announced.
  • Interacting with a running background subagent: arrow-down + enter to message it while it works (per thread replies); separate tabs for background agents are coming.
  • Demand surfaced in replies (not confirmed shipping): persistence, naming, skills, directories, inter-agent communication, and a “merger” step for reconciling parallel work. ^[inferred — these are community requests surfaced in thread replies, not confirmed roadmap items]
  • First-party post from Claude Code’s creator; the exact shipping version is unconfirmed. ^[inferred — 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
  • Background execution by default (2026-06-29): subagents run in the background by default in the next Claude Code version — you keep working with the main instance while they run; instruct Claude explicitly to force a subagent to run in the foreground instead
  • 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?
  • Partially resolved 2026-07-16: Anthropic’s steering-Claude-Code post confirms only the subagent’s final message (summary plus metadata) returns to the parent session — the larger instructional body never enters it at all — but doesn’t quantify a token ceiling on that returned summary, so “how much context can a subagent return before the parent is impacted” remains open as a quantitative question.
  • Can subagent definitions in .claude/agents/ reference MCP servers or skills?
  • What Claude Code version number ships background-by-default subagent execution, and is the rollout fully complete or still gradual?

Graph View

Backlinks