Jonathon's AI Wiki

Claude Code Subagents

7 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]

Cross-provider limit: a fork must match its parent’s model (2026-08-25)

A constraint worth stating plainly because it blocks an otherwise obvious cost pattern.

  • A normal subagent starts with fresh context by design. It receives the delegated task and the applicable project instructions — not the parent conversation, and not every file the parent read. That bounded context is why subagents are good at narrow work and why their logs and side investigations stay out of the main conversation.
  • A forked subagent does receive the full conversation and can reuse the parent’s prompt cache. The trade-off: a fork must use the same model as the parent.
  • Claude Code documents how a subagent chooses its model. It does not document a separate provider address per subagent. So there is no native configuration for “the parent stays on Anthropic, but send this one child to a cheaper third-party provider.”

The consequence for anyone trying to run a cheap worker beside an expensive lead is that the supported answer is two sessions, not one delegation — an ordinary session as lead, a second session launched against the other provider as worker, an explicit written handoff between them, and a git worktree if both will edit concurrently. Full pattern: Running a Cheap Model Beside Your Expensive One. A gateway or custom integration is described as possible but is explicitly not recommended for beginners in that source.

Field report: effort level can multiply subagent count (2026-08-25)

An r/ClaudeCode post (score 20, 18 comments) reports asking for an xhigh /code-review on a 430-line script and Claude “immediately trying to spawn 10 Fable-level subagents.” The poster stopped it at five, by which point it “had already burned through almost 200k tokens.”

Recorded as an unverified single field report, but the shape is plausible and the lesson is cheap: raising review effort raises fan-out, and fan-out at a frontier model is the expensive axis — the cost is roughly effort × agents × model price, not effort alone. Match the review depth to the size of the diff, not to the importance you feel about it. See Model vs. Effort.

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

  • Can a gateway give one subagent a different provider? Described as possible in the 2026-08-25 source but not detailed, and explicitly not recommended for beginners. Untested here.

  • What actually drives subagent fan-out at high effort? The 10-subagents-on-430-lines report is a single unverified case. Whether fan-out scales with effort, with diff size, with both, or is non-deterministic is undocumented.

  • 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