Subagents in Claude Code

Your context window is finite — subagents spend someone else's

Long sessions die of context pollution: every file read, every test log, every dead end lands in the one window you have. A subagent is a specialized assistant Claude Code delegates a task to — it gets its own context window, its own system prompt, and its own tool permissions, does the work with a clean slate, and hands back only the result.

That one move buys five things at once: context preservation, specialized expertise with higher success rates, reusability across projects and teams, flexible permissions per agent type, and parallel scale — multiple agents on different aspects simultaneously.

Delegation runs 60k tokens of work — your window pays for the summary

An agent is a Markdown file — /agents writes it for you

---
name: test-runner
description: Use proactively to run
  tests and fix failures
tools: Read, Edit, Bash   # optional
model: sonnet            # optional
---

You are a test automation expert.
When you see code changes, run the
tests. If they fail, fix them while
preserving the original test intent.

Four places define agents — closest to the session wins

• Duplicate names → the higher-priority source shadows the lower one
• claude agents lists everything grouped by source — and flags the overrides
• --agents JSON needs description + prompt; tools and model optional — perfect for scripted, one-session agents

A dozen optional fields tune tools, models, and behavior

Six built-ins are already running — you've used subagents all along

Describe the task and Claude delegates — or name the agent and guarantee it

Agents resume with full context and chain into pipelines

> Use the code-analyzer agent to start
  reviewing the authentication module
# returns agentId: "abc123"

> Resume agent abc123 and now analyze
  the authorization logic as well

> First use the code-analyzer subagent
  to find performance issues,
  then use the optimizer subagent
  to fix them

memory: gives an agent knowledge that compounds across sessions

• The first 200 lines of MEMORY.md auto-load into the agent's system prompt each run
• Read, Write, Edit are auto-enabled so the agent manages its own memory files
• The agent can grow extra files in its directory as its knowledge accumulates

background: true keeps slow work off your main thread

A background subagent runs while you keep working — set background: true in frontmatter to make an agent always run that way, or press Ctrl+B to background a task that's already running.

isolation: worktree lets an agent edit without touching your tree

context: fork starts the agent knowing everything you know

The clean slate is the default — and usually the point. context: fork inverts it: the subagent inherits the parent's full conversation at the moment of forking, explores an alternative path, and reports back without disturbing the original. GA in v2.1.117; on external builds set CLAUDE_CODE_FORK_SUBAGENT=1.

Teams are peers with a mailbox — subagents are specialists with a report

Agent Teams (experimental, off by default, v2.1.32+) coordinate multiple full Claude Code instances: a team lead assigns work through a shared task list with automatic dependency tracking, and teammates message each other directly through a mailbox.

Teams need one env var — and a task list that runs itself

The runtime has rules: no nesting, scoped plugins, traceable spend

Nine ready-made agents ship with this chapter — tool grants match the job

Delegate the heavy, skip the quick — and give every agent one job

Isolation is the whole game — everything else is configuration

A subagent is a Markdown file: frontmatter sets the tools, model, and permissions; the body is the system prompt. The description decides when Claude delegates automatically. Of every feature so far, subagents are the only one with an isolated context window — and four fields extend it: memory persists knowledge, background unblocks your thread, isolation: worktree protects your tree, context: fork shares your history. When specialists need to talk to each other, that's agent teams.