Claude Code Subagents Explained: When and How to Use Them

2026-02-19

Subagents are one of Claude Code's most powerful features — and one of the least understood. They let Claude spawn separate Claude instances to handle tasks in parallel, each with their own context window.

What is a subagent?

When Claude Code uses the Agent tool, it launches a new Claude instance (a "subagent") that runs independently. The subagent gets its own context, does its work, and returns a result to the parent. The parent never sees the subagent's intermediate steps — just the final output.

Think of it like delegating to a colleague: you give them a task, they go figure it out, and they come back with the answer.

Why subagents matter

Claude Code has a context window. Every file it reads, every tool result, every message — it all takes up space. When you're working on a large task, the context fills up.

Subagents solve this by offloading work into separate contexts. The parent stays focused on the big picture while subagents handle the details.

When Claude uses subagents

Claude Code uses subagents automatically in several situations:

• Exploring the codebase — scanning files across many directories
• Running tests — executing test suites and analyzing results
• Research tasks — searching the web or reading documentation
• Parallel work — doing multiple independent things at once

You can also explicitly ask Claude to use subagents: "use subagents to search for all uses of this API across the codebase."

Subagent types

Claude Code has several built-in subagent types, each with different tool access:

The Explore type is the most commonly used — it's fast and can't accidentally modify anything.

How to get the most out of subagents

Be specific in your requests

Instead of "find where we handle auth", try "find all files that import from src/lib/auth and show me how they use the requireAuth middleware."

Claude translates your request into a subagent prompt. The more specific you are, the better the subagent prompt.

Ask for parallel subagents explicitly

If you have multiple independent questions, say so:

"In parallel, find: (1) all API routes that don't have rate limiting, (2) all database queries that aren't using parameterized inputs, and (3) all files importing the deprecated oldAuth module."

Claude will launch multiple subagents simultaneously instead of doing these sequentially.

Use subagents for large refactors

When refactoring across many files, combine subagents with plan mode to explore the impact before making changes:

"Before renaming the UserService class, use subagents to find every file that references it, including tests, imports, and type declarations."

Know when NOT to use subagents

Subagents add overhead. For simple, directed tasks — reading one file, making one edit — they're slower than just doing it directly. Don't ask Claude to "use a subagent to read package.json." That's like scheduling a meeting to ask one question.

Subagents in custom skills

If you're writing custom Claude Code skills, you can control subagent behavior:

Use the Agent tool with subagent_type="Explore" to search the codebase
for all React components that accept a `userId` prop.

Skills that need to explore before acting often follow a two-phase pattern: subagent explores, then the main agent acts on the findings.

Subagents vs skills vs hooks

These three extension points serve different purposes:

• Subagents — Claude spawning Claude to handle subtasks. Managed by Claude itself.
• Skills — Reusable prompts/workflows you can invoke with /skill-name. Defined by you.
• Hooks — Shell commands that fire on events (file write, session start). Defined by you, enforced by the system.

Subagents are the only one of these that Claude controls autonomously. Skills and hooks are extensions you configure. See our detailed comparison of skills, plugins, and subagents for more on how these extension points relate.

Watching subagents work

When Claude launches subagents, you'll see them appear in the interface as nested operations. Each subagent shows its own tool calls and progress. When it finishes, the result flows back to the parent.

If a subagent is taking too long or going in the wrong direction, you can interrupt it just like you'd interrupt the main agent.

Tips

Subagents don't share context with the parent. The parent has to explicitly pass relevant information in the subagent prompt. If the subagent needs to know about a decision made earlier in the conversation, the parent must include it.

Subagents are great for validation. After making changes, Claude can spawn a subagent to review the diff, run tests, or check for regressions — all without cluttering the main context.

Don't micromanage subagent usage. Claude is generally good at deciding when to use subagents. If you find yourself constantly telling it to use or not use them, consider adding a note to your CLAUDE.md about your preference.