Subagents & Parallel Agents

Your main conversation is a single context window. Every file Claude reads, every grep result, every verbose log dumps tokens into that one window — and as it fills, quality degrades. A subagent is the fix: a helper Claude spawns that runs in its own, separate context window, does a chunk of work there, and reports a summary back to the main thread. The heavy lifting — the hundred files it read, the dead ends it explored — never touches your main conversation.

Think of it as delegating to a colleague at their own desk. They can see the conversation that led to the request, but they start fresh — they don't inherit your full working memory, and you don't inherit theirs. When they're done, they hand you a one-page summary, not their entire scratch pad.

MAIN CONVERSATION  (stays clean — only sees the summary)
        │  delegates a task
        ▼
   ┌─────────────────────────────┐
   │  SUBAGENT (isolated context)│  reads 100 files, greps,
   │  explores freely, burns     │  tries dead ends — none of
   │  tokens in its own window   │  this lands in your thread
   └─────────────────────────────┘
        │  reports a SUMMARY
        ▼
MAIN CONVERSATION  (continues, uncluttered)

This is why subagents shine for large, independent exploration: "map every place we call the payments API," "figure out why this test is flaky," "audit the codebase for hardcoded secrets." Each is a self-contained investigation whose raw output you don't want polluting the main window — you just want the answer.

There's a subtlety that trips people up. A subagent can see the conversation that spawned it — it has the context of why it was asked. But it starts fresh: it does not carry your full accumulated working state, and crucially it may not internalize your project's conventions unless you say so.

The practical consequence: pass project conventions explicitly in the task description. Don't assume the subagent "already knows" that you use 2-space indentation, that tests live in __tests__/, or that the team forbids a particular library. A vague delegation gets a vague, off-convention result.

A weak task description:

Go review the auth module.

A strong one:

Review src/auth/ for security issues. Conventions: we use Zod for all
input validation, never raw try/catch around DB calls (use the withDb()
helper), and all errors must go through reportError(). Flag any deviation.
Return a prioritized list with file:line references — no code edits.

The second version tells the fresh-context subagent exactly what "correct" looks like and exactly what to hand back. The richer the task description, the better the summary you get.

There are two ways to create reusable subagents.

1. The --agents flag (JSON, at launch). Pass a JSON object keyed by agent name. Each entry carries the frontmatter-style fields plus a prompt — its standing instructions:

claude --agents '{
  "reviewer": {
    "description": "Reviews diffs for correctness and security, no edits",
    "prompt": "You are a meticulous code reviewer. Read the diff, flag correctness bugs, security issues, and convention violations. Return a prioritized list with file:line references. Never edit files."
  }
}'

The shape is {name: {description, prompt}}. The description tells Claude when to reach for this agent; the prompt is how it behaves once invoked. You can define several agents in one object.

2. The /agents manager (interactive). Run /agents inside a session to open the subagent manager — create, edit, and inspect agent configurations through a UI, and set up the agents a project needs without hand-writing JSON. This is the recommended entry point for a first session in a repo (alongside /init, /memory, and /mcp).

Once defined, an agent can be invoked by Claude when its description matches the task, or you can direct work to it explicitly.

The most useful subagent pattern exploits a simple truth: the context that wrote the code is biased toward believing it's correct. It just spent effort producing the change; it's primed to rationalize. A reviewer in a fresh context has no such investment — it reads the diff cold and judges it on its merits.

So split the work across contexts. One actor (the main conversation, or a Writer subagent) produces the change. A separate Reviewer subagent — fresh context, no memory of the design decisions — reviews it.

Main context  →  writes the feature
      │
      ▼
Reviewer subagent (fresh context)  →  reads only the diff + conventions
      │
      ▼
Returns findings  →  main context fixes them

The fresh context is doing the work here. Because the reviewer didn't see why each choice was made, it can't be talked into accepting a shortcut — it sees only what's actually on the page. Give it the diff and the conventions, and ask for a prioritized findings list with file:line references rather than edits, so you stay in control of the fixes.

This is the same principle behind running review as a separate session entirely — Session A writes, Session B reviews with no shared state. Subagents bring that benefit inside a single conversation.

Writer/Reviewer asks "is this good?" An adversarial subagent asks the sharper question: "how is this wrong?" Instead of evaluating quality neutrally, you task the subagent to actively try to refute the result — to find the input that breaks it, the assumption that doesn't hold, the test that's quietly passing for the wrong reason.

The framing matters. Compare:

# Neutral reviewer
Review this caching layer for issues.

# Adversarial subagent
Your job is to PROVE this caching layer is broken. Find a sequence of
operations that returns stale data, a concurrency race that corrupts the
cache, and any input that bypasses invalidation. Assume it's buggy until
you've genuinely failed to break it. Report every refutation with a
concrete reproduction.

The adversarial prompt produces a different search — the subagent hunts for counterexamples instead of confirming the happy path. Because it runs in isolated context, it can explore aggressively (read everything, trace every branch) without bloating your main thread, and it reports back only the refutations it found.

Use adversarial review for anything where being confidently wrong is expensive: security boundaries, concurrency, data migrations, financial calculations. Pair it with a verifier — when the adversary claims a break, have it produce a failing test, so the refutation is reproducible, not just asserted.

When a change is too big for one agent but cleanly splits into independent pieces — "migrate every component from Solid to React," "add a license header to all source files," "convert all tests from Jest to Vitest" — the /batch command orchestrates the fan-out.

/batch migrate src/ from Solid to React

Here's the full pipeline /batch runs:

Two properties make this safe to run wide. First, isolation: each unit gets its own git worktree, a separate directory, so parallel subagents never collide on each other's edits. Second, the plan gate: you see the decomposition before anything runs, so you can catch a bad split before 20 agents act on it. /batch requires a git repository (worktrees and PRs depend on git).

Under the hood, /batch is a bundled workflow that fans work out across many subagents and runs in the background — monitor the running units with /tasks, and the detached agents with claude agents.

Subagents are one of three extension mechanisms, and they're easy to confuse. The distinction is about who triggers the behavior and what guarantee you get.

The sharpest line is hooks vs. everything else. Hooks are deterministic shell commands wired to lifecycle points in .claude/settings.json — they always fire. Subagents and skills are model-invoked and best-effort: Claude decides to use them based on the situation. If you need a guarantee ("never let a commit through without running the linter"), that's a hook, not a subagent and not a CLAUDE.md note.

Between subagents and skills: a skill is on-demand knowledge or a workflow the model reaches for within the current flow; a subagent is delegated work that runs in an isolated context and hands back a summary. Reach for a subagent specifically when you want the work done elsewhere to keep the main conversation clean.