Claude Code Subagents Explained

Claude Code subagents are parallel workers that the main agent spawns to handle independent parts of a task. Each subagent gets its own context, runs its own tools, and reports results back to the parent.

Subagents solve the context-pollution problem. When one agent tries to review security, check performance, and verify tests all at once, it loses focus. Subagents let each concern run in isolation with full attention.

This guide covers how Claude Code subagents work, the built-in agent types, worktree isolation for safe parallel edits, and practical patterns for teams using subagents in production workflows.

What Claude Code subagents are

A subagent is a separate Claude Code instance spawned by the Agent tool. The parent agent writes a prompt describing the task, and the subagent runs independently with its own conversation context and tool access.

Subagents run in the background by default. The parent agent can launch multiple subagents at once and continue working while they run. When a subagent finishes, it reports its findings back to the parent.

Each subagent starts fresh. It does not see the parent's conversation history. This means the prompt you give a subagent must be self-contained: include the goal, relevant file paths, what to look for, and how to report results.

• Subagents run independently with their own context.
• Multiple subagents can run concurrently in the background.
• Each subagent starts fresh with no parent conversation history.
• The spawning prompt must be self-contained with full context.

Built-in Claude Code agent types

The Explore agent type is read-only and fast. It searches code, reads files, and reports findings without making changes. Use it for questions like where is the auth middleware defined or which files import the pricing module.

The general-purpose agent has access to all tools including file edits and shell commands. Use it for tasks that require changes, like refactoring a module or adding test coverage.

The code-reviewer agent focuses on reviewing code quality, finding bugs, and checking standards. The Plan agent is read-only and designs implementation strategies without executing them.

You can also define custom agent types in .claude/agents/ with specific models, tools, and instructions tailored to your team's needs.

• Explore: read-only, fast search and code lookup.
• General-purpose: full tool access for edits and commands.
• Code-reviewer: focused on quality review and bug detection.
• Plan: read-only architecture and implementation planning.
• Custom: defined in .claude/agents/ with your own constraints.

Worktree isolation for safe parallel edits

When two subagents edit the same repo at the same time, their changes can conflict. Worktree isolation solves this by giving each subagent its own temporary git worktree, a separate copy of the repo with its own working directory.

You enable worktree isolation by passing isolation: worktree when spawning the agent. The subagent works on its isolated copy. If it makes changes, the worktree path and branch name are returned. If it makes no changes, the worktree is automatically cleaned up.

This is critical for parallel refactoring. You can launch three subagents to update three different modules at the same time. Each works in its own worktree. When all three finish, you review and merge each branch separately.

• Each worktree is a full, isolated copy of the repo.
• Set isolation: worktree when spawning the agent.
• No-change worktrees are auto-cleaned.
• Changed worktrees return a branch name for review and merge.

The fan-out search pattern

Fan-out is the most common subagent pattern. The parent agent needs to answer a broad question, so it spawns multiple Explore agents to search different parts of the codebase at once.

Example: a developer asks how the app handles authentication. The parent spawns three Explore agents. One searches the API layer for auth middleware. Another checks the frontend for login components. A third searches configuration files for auth providers. All three run in parallel and report back in seconds.

The parent agent then synthesizes the results into a single answer. This is faster than one agent searching sequentially and produces better results because each agent focuses on one area.

• Spawn multiple Explore agents for different search areas.
• Each agent searches one layer or module independently.
• The parent synthesizes results into a unified answer.
• Parallel search is faster and more thorough than sequential.

Parallel review with specialized agents

Code review benefits from specialized subagents because different concerns need different expertise. A security reviewer checks for injection, authentication gaps, and data exposure. A performance reviewer checks for N+1 queries, missing indexes, and memory leaks. A style reviewer checks for naming, structure, and documentation.

Launch all three as separate subagents pointed at the same diff. Each applies its own checklist without being distracted by the others. The parent collects all findings and presents a unified review.

This pattern catches more issues than a single reviewer because each subagent applies full attention to its domain. A single agent reviewing for everything tends to do a shallow pass on each concern.

• Security agent: injection, auth gaps, data exposure.
• Performance agent: N+1 queries, missing indexes, memory.
• Style agent: naming, structure, documentation.
• Unified review catches more than a single shallow pass.

Multi-file refactoring with subagents

Large refactors often touch many files that are independent of each other. Renaming a function across 20 files, updating an import path in every module, or migrating a config format across services are all parallelizable.

Spawn one general-purpose subagent per module or file group, each with worktree isolation. The prompt tells each agent exactly which files to change and what the change looks like. Each agent works in its own worktree, so there are no merge conflicts during the run.

After all agents finish, review each worktree branch. Merge them sequentially. If one branch has a problem, you can fix or discard it without affecting the others.

• Split refactors into independent file groups.
• One subagent per group with worktree isolation.
• Review and merge each branch independently.
• Discard a bad branch without losing other changes.

How to prompt Claude Code subagents

Write subagent prompts like a briefing for a colleague who just walked in. They have not seen your conversation. They do not know what you tried. They do not know why this matters.

Include the goal, relevant file paths, what to look for, what format to report in, and any constraints. Bad subagent prompts say find the bug. Good subagent prompts say check src/api/auth.ts for cases where the JWT expiration is not validated before granting access. Report file path, line number, and severity.

Keep subagent prompts focused on one concern. A subagent that tries to do three things will do all three poorly. If you need three things, spawn three agents.

• Include goal, file paths, search criteria, and report format.
• Write the prompt as if briefing someone with no context.
• One concern per subagent for best results.
• Specify the output format so the parent can synthesize easily.

Subagent costs and practical limits

Each subagent consumes its own tokens. Five subagents running in parallel use roughly five times the tokens of one agent doing the same work sequentially. The tradeoff is speed: parallel runs finish in the time of the slowest agent, not the sum of all agents.

Set practical limits. Most tasks need two to four subagents. More than six subagents usually means the task should be broken into separate sessions instead. Watch for redundant work where two agents search the same files.

Background subagents report automatically when done. Do not poll or check on them. The parent agent is notified when each subagent completes.

• Parallel subagents trade tokens for speed.
• Two to four subagents covers most use cases.
• More than six usually means the task needs restructuring.
• Do not poll. The parent is notified on completion.