Subagents

Subagents are separate Claude instances you launch from a main session to handle a focused task in their own context window. Use them to parallelize independent work, or to isolate a noisy task (large search, broad refactor) so its file dumps don't bloat your main context. The win is fresh context per task: quality starts to degrade once a window is ~45% full, and a subagent resets that clock.

The communication model is delegate-and-return: the main agent hands off a task, the subagent works in isolation, and only its final summary comes back, not the full transcript. That summary is the whole interface, so the brief in and the summary out are what matter.

How you use it day-to-day

• Fan-out search. Delegate multi-file sweeps and "find where X happens" questions, keeping the conclusion, not the file dumps. Use Explore (fast, read-only) for this.
• Plan before building. Use the Plan agent to research and return a step-by-step plan; use general-purpose for complex multi-step execution.
• Parallel streams. Run genuinely independent work concurrently, one agent per stream, and launch them in a single message so they actually run in parallel.
• Custom agents. Drop definitions in ~/.claude/agents/ (user-level) or .claude/agents/ (project-level) with a name, description, and an allowed-tools list to scope a repeatable role.

Gotchas

• The subagent's final message is the only thing returned. You don't see its work mid-run, so write the brief expecting a one-shot handoff.
• A fresh agent starts without your conversation history. It inherits CLAUDE.md, MCP servers, and skills, but not what you've discussed, so brief it explicitly. (This is why CLAUDE.md quality matters even more when you delegate.)
• Nesting depends on the surface. In the Agent SDK, subagents can spawn their own since Claude Code 2.1.172 (foreground at any depth; a background subagent is capped five levels below the main agent). The interactive Agent tool and the Workflow tool nest one level only. Default to one level unless you're on the SDK.
• For a single fact in a file you already know, just read it. Delegation has overhead; it pays off on breadth, not on one lookup.

Subagents vs Agent Teams vs Workflows: subagents are hub-and-spoke interns (do task, report back). Agent Teams are full peer sessions that message each other and share a task list. Workflows script fan-out across many agents with verification. Three distinct orchestration tools; see the Workflows page for the scripted-fan-out end.