Claude Code Subagents: Parallel Agents

Subagents are useful when a task can be split cleanly: one agent searches the authentication code, another traces the database path, and the main conversation compares what they found. They add little to “read this file” or to work where every step depends on the same context.

Short version: delegate independent research or a separate review when the results are worth the extra context and usage. Give each agent a narrow scope, the files or area to inspect, and a specific report format. Keep dependent work in the main conversation.

If you want a step-by-step walkthrough of launching one, see the subagent spawning guide.

Subagents can have their own instructions, tool access, and permissions. They start with a separate context, but by default work from the main conversation’s current directory. That means “separate context” does not necessarily mean “separate files.” If you want a repeatable checklist in the main context, a Claude Code Skill may fit better. For the boundary between those and commands, see the Skills vs slash commands guide.

What Claude Code subagents do

A subagent takes on a task Claude Code delegates, works in its own context window, and returns a result for the main conversation to use. It does not automatically receive the full conversation history. Claude Code gives it a task brief, and custom subagents also have their own system prompt and configured tools.

That separation helps with searches that would otherwise fill the main context with file matches, logs, or documentation. It also gives you a way to restrict a reviewer to read-only tools. It does not make the result automatically correct: check the evidence and decide what to use.

When to delegate, and when to stay in the main conversation

Use a subagent when the work can proceed independently and its detailed trail is less useful than its conclusion:

• Investigate separate modules or competing hypotheses in parallel.
• Search a large codebase or logs, then return only relevant paths and evidence.
• Ask for an independent review with explicit criteria.
• Repeat a specialized task often enough to justify a custom subagent.

Stay in the main conversation for a quick lookup, a small edit, frequent back-and-forth, or a sequence where each step needs the previous step’s context. Delegation has overhead: each agent needs a useful brief, spends its own usage, and sends results back into the main conversation. More agents can mean more work to reconcile, not a proportionally faster result.

A worked split: investigate a slow API route

Suppose an endpoint is slow and you do not yet know whether the delay comes from authentication, database access, or an external API. Those are plausible independent investigations. Ask Claude Code to delegate one area to each subagent and request the same evidence from all three:

Investigate the latency in `src/app/api/report/route.ts` using three
independent read-only subagents:
 
1. Trace authentication and session work.
2. Trace database queries and their callers.
3. Trace external network calls and retry behavior.
 
For your area, report the files and lines inspected, the request path,
the strongest evidence for a likely delay, and what you could not verify.
Do not edit files or guess at timings. I will compare the findings before
choosing a fix.

This split works because the three agents can trace different code paths without waiting on each other. If the database result shows that the auth path is misleading, you can then ask a focused follow-up in the main conversation. Splitting a single five-line helper lookup across agents would add coordination without useful parallel work.

Anthropic’s subagent guide recommends parallel subagents for independent investigations and notes that returned detail also consumes context. The key condition is independence, not the number of agents.

Write a brief that can be checked

A subagent cannot infer missing product context or know what “done” means unless the delegation message tells it. Include:

1. Goal: the question it should answer.
2. Scope: paths, files, or systems to inspect.
3. Constraints: for example, read-only, no network calls, or don’t touch generated files.
4. Evidence: ask for paths, line numbers, commands, or source links.
5. Output: a verdict, findings, uncertainty, and anything it could not verify.

For example, “review the migration” leaves too much open. Say which migration, what risk to inspect, and the evidence needed to support the verdict. Keep unrelated implementation instructions out of a research brief.

Create a focused custom subagent

Create a project subagent in .claude/agents/ or a personal one in ~/.claude/agents/. The project file can be checked into version control and shared with the team. A custom subagent file has YAML frontmatter followed by its instructions. Only name and description are required; use tools to narrow its capabilities.

Here is a read-only API reviewer:

---
name: api-reviewer
description: Reviews API routes for validation, authorization, and error handling when asked to inspect an endpoint.
tools: Read, Grep, Glob
model: inherit
---
 
Review the API route named in the task.
 
- Trace input validation, authentication, authorization, and error handling.
- Inspect only relevant callers and helpers.
- Do not edit files or claim runtime behavior you did not verify.
- Return findings with file paths, line numbers, impact, and uncertainty.
- If you find no issue, summarize what you checked and any limits.

tools is the documented frontmatter field. allowed-tools is not the field used by the current subagent configuration reference. The example intentionally grants no Edit or Write tool; it still depends on the session’s permissions and the exact tools available in that environment.

Keep the description specific enough for Claude Code to know when the agent applies. Put its detailed checklist in the body. Create one when the same specialized task recurs; for a one-off, an inline delegation brief is usually simpler.

Avoid overlapping edits

Subagents can modify files when their tools and permissions allow it. By default, they start in the main conversation’s current working directory, so concurrent edits can land in the same checkout. Give implementation agents distinct file ownership, and inspect git status and git diff before accepting their work. If two tasks need the same file, serialize them or have one agent return a proposed patch for the main conversation to apply.

For stronger filesystem separation, a subagent can use isolation: worktree. That gives it a separate worktree; its changes then need review and deliberate integration. A worktree reduces accidental overlap, but it does not resolve semantic conflicts for you. Read Anthropic’s worktree isolation details before relying on a particular setup.

If a delegation returns an error or an incomplete report, check whether the requested subagent type and tools are available, then narrow or correct the task. Ask for missing evidence directly. A confident summary without traceable evidence is still only a lead, not a verified diagnosis.

Use the smallest split that produces useful independent results. A research agent can report evidence; a separate implementation agent can then own a bounded change; a reviewer can inspect that diff. If the tasks share files or require constant coordination, keep them together and work through the steps in order.

Related: Claude Code Agents - how they work and when to use them · Claude Code Skills - workflows you reuse · Claude Code Plan Mode - shortcut and full guide · Claude Code MCP - connect servers and add tools