Subagents — AIGuide

The concept

What is a subagent?

A subagent is a full agent in its own right — model, tools, a loop — but it's spawned by another agent to handle a focused task. The main agent (the orchestrator) delegates a job, the subagent runs independently, and when it's done it returns a concise summary. Its entire working history stays inside its own context and never crowds the main conversation.

🧹

The clean-desk rule, revisited

Remember the manager and the intern from the Basics? The subagent is that intern: it reads the whole archive at its own desk and walks back with one sticky note. The orchestrator's desk — its context window — stays clear.

The whole reason they exist

Context isolation is the point

Everything good about subagents flows from one fact: each gets a fresh, separate context window. It sees its own system prompt and the task it was handed — not the main conversation's history. Only its summary crosses back.

🔒One-way mirror. The orchestrator can read a subagent's result; the subagent can't read the orchestrator's earlier work. That asymmetry preserves isolation.
🧾Separate transcripts. A subagent's full history is stored on its own, so nothing bloats the parent — and it can be resumed later with its context intact.
💸Cheap parallelism. Five subagents = five separate windows. Running them at once doesn't bloat any single one.
🎯Specialised focus. Each can have a tailored system prompt, a restricted toolset, and even a different model — tuned for exactly one job.

🧠

Mental model

Isolation turns an expensive "read everything into one huge context" problem into many small, disposable contexts whose only lasting output is a tidy summary. That's what makes delegation a net win instead of just more overhead.

Make your own

Defining a subagent

A custom subagent is a Markdown file: YAML frontmatter that tells Claude when to use it and what it may touch, followed by a system prompt that tells it how to behave. Drop it in .claude/agents/ (this project) or ~/.claude/agents/ (all your projects).

--- name: code-reviewer description: Reviews a diff for bugs and risky changes. Use proactively right after code is written or edited. tools: Glob, Grep, Read # read-only — it can't edit model: sonnet --- # This body becomes the subagent's system prompt. You are a meticulous code reviewer. Inspect the changes, list concrete bugs with file:line references, and rank them by severity. Be terse. Do not fix anything — only report.

Two fields do the heavy lifting: description (how the orchestrator decides to delegate) and the body (how the subagent behaves). Everything else is optional tuning.

🎯

The description is a trigger, not a label

"Reviews a diff for bugs… use proactively after edits" gets delegated to at the right moments. "A code helper" does not. Write the description as the situation that should invoke it.

Every dial

Frontmatter reference

Only name and description are essential. The rest lets you shape a subagent precisely.

Field	Type	What it does
`name`	string	Unique, lowercase-hyphenated id. Required.
`description`	string	When to delegate to it. "Use proactively" encourages auto-delegation. Required.
`tools`	list	Allowlist of tools. Omit to inherit all. Restrict for safety (e.g. a read-only reviewer).
`disallowedTools`	list	Denylist — applied before the allowlist.
`model`	enum	`haiku` · `sonnet` · `opus` · `fable` · `inherit`. Match the model to the job's difficulty.
`permissionMode`	enum	Its autonomy posture: `default` · `acceptEdits` · `plan` …
`maxTurns`	int	Caps its loop length — a safety backstop against runaways.
`skills`	list	Skills to preload into the subagent's context.
`memory`	enum	Persistent cross-session memory: `user` · `project` · `local`.
`isolation`	enum	`worktree` = run in a separate git worktree so parallel edits can't clash.
`effort`	enum	Reasoning-effort override: `low` → `max`.

Files live at four scopes, highest priority first: enterprise-managed, project (.claude/agents/), personal (~/.claude/agents/), and plugin-bundled.

Getting one to run

How subagents are invoked

Automatic delegation

Describe the work naturally. The orchestrator reads every agent's description and delegates when one fits — the "use proactively" hint nudges this.

Explicit @-mention

Type @agent-code-reviewer to guarantee that specific subagent runs.

Session-wide flag

Launch with claude --agent code-reviewer to use it for the whole session.

🎁

What comes back — and what stays

The orchestrator receives only the final summary plus an id it can use to resume that subagent later (its context is preserved). Every file the subagent read and every log it produced stays in its transcript, out of the main window.

Batteries included

Built-in subagents

You don't have to write any config to start — Claude Code ships with ready-made subagents it delegates to automatically.

🔍

Explore

Read-only file discovery & codebase search. Runs on a lighter, faster model.

🗺️

Plan

Gathers context, then proposes a strategy before any edits.

🧰

General-purpose

Complex tasks needing both exploration and code changes.

⌨️

Bash

Runs terminal commands in an isolated context so output doesn't flood the chat.

Scale

Parallelism & nesting

Because each subagent has its own window, the orchestrator can run several at once — a fan-out — and collect all their summaries. Subagents can also spawn their own subagents, nesting a bounded number of levels below the main conversation.

Wall-clock time is the slowest single subagent, not the sum — that's why parallel delegation is fast.

📐

Guardrails on scale

Concurrency is capped so a burst of subagents doesn't overwhelm your machine, and nesting depth is bounded so delegation can't recurse forever. You get parallel speed without a runaway.

The playbook

Orchestration patterns

These are the reusable shapes for putting subagents to work. Mix and match them.

✅

Verification loop

Do the work, hand it to a read-only checker subagent, feed the critique back, and loop until clean. Keeps noisy review output out of the builder's context.

🌐

Fan-out / fan-in

Split independent work across parallel subagents, then merge their summaries in one synthesis step. Best when the pieces don't depend on each other.

➡️

Pipeline

Chain specialised subagents so each one's output feeds the next: Explore → Plan → Implement → Review → Test.

🔁

Loop-until-done

A subagent retries the same task, self-checking each pass, until a clear condition is met. A resumed subagent keeps its context, so it learns from earlier attempts.

⚔️

Adversarial verification

Spin up independent skeptics whose only job is to refute a finding — default to "rejected" unless the evidence convinces. Kill any claim a majority refute. Give each a distinct lens (correctness, security, "does it actually reproduce?") so diversity catches failures redundancy would miss. This is how you stop plausible-but-wrong results from surviving.

Editing in parallel safely

Worktree isolation

Context isolation keeps reasoning separate — but what if several subagents need to edit files at the same time? They'd trip over each other in one working directory. The fix is isolation: worktree: each subagent runs in its own git worktree, a separate checked-out copy of the repo.

🌳No collisions. Each agent edits its own copy; their changes are reconciled afterward instead of clobbering each other live.
🧽Auto-cleanup. A worktree that ends up unchanged is removed automatically, so you're not left with clutter.
⚖️Use it deliberately. Worktrees cost setup time and disk — reserve them for genuinely parallel edits, not read-only work.

Judgement

When to use a subagent — and when not to

✓ Reach for one when…

✓A side-task would flood the main context with searches, logs, or big file reads you won't reference again.
✓You want independent work done in parallel — reviewing several modules at once.
✓A job benefits from a specialised prompt or restricted tools (a read-only reviewer, a test-runner).
✓You want an independent second opinion that isn't primed by the main conversation.

✗ Skip it when…

✗The task is a quick one-liner — the delegation overhead isn't worth it.
✗The work needs the full conversation's context, which a fresh subagent can't see.
✗You'd spawn so many that coordinating their summaries costs more than doing it inline.

🎯

Rule of thumb

Delegate the noisy and the parallel. Keep the core reasoning — the part that needs the whole story — in the main agent.

In your editor

Subagents in VS Code

Inside the VS Code extension, subagents work just like the CLI — they share the same .claude/agents/ folders and settings.

Create them in the file explorer — add a .claude/agents/name.md file right in your editor.
Watch delegation happen — the chat panel shows when work is handed to a subagent and when its summary returns.
Run several conversations in tabs to keep parallel threads of work organised.

The full picture

Agents, subagents, skills & the loop

A single agent runs the loop; subagents let it delegate and parallelise; skills give it the know-how. Put them together with good loop engineering and you have a dependable, scalable assistant.

Next lesson: Skills Skip ahead: Advanced patterns