Subagents

Use Claude Code subagents to isolate context, run focused work in parallel, and build reusable specialist workers.

What Subagents Are

Subagents are separate Claude workers spawned from a main session. Each subagent gets its own context window, instructions, tool access, and permission behavior. The main session delegates a task, the subagent works independently, and the result comes back as a summary.

Use a subagent when a task would flood your main conversation with search results, logs, test output, or file contents you do not need to keep reading.

Built-In Subagents

Claude Code includes built-in subagents that it can use automatically:

You usually do not need to call these by exact name. Ask naturally:

Use a subagent to inspect the auth module and report the likely root cause.
Keep the main conversation clean; return only findings and relevant files.

Foreground vs Background

Subagents can run in the foreground or background.

• Foreground: the main conversation waits for the subagent. Permission prompts are surfaced to you as they happen.
• Background: you keep working while the subagent runs. It uses already-granted permissions and auto-denies actions that would require a fresh prompt.

Ask for background work explicitly:

Run a background subagent to execute the full test suite.
Report only failing tests and error messages.

If a background subagent fails because it needed approval, retry as a foreground subagent.

Custom Subagents

Create custom subagents with /agents or with Markdown files under .claude/agents/ or ~/.claude/agents/.

---
name: security-reviewer
description: Use after API or auth changes to review for security risks.
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: plan
---

You are a security reviewer. Inspect the changed files and nearby code.
Focus on auth bypass, missing validation, injection risks, secrets, and unsafe logging.
Return findings with file paths, severity, and a concrete fix.

Good descriptions matter. Claude uses the description field to decide when a subagent should be used.

Tool and Permission Boundaries

Subagents inherit tool access unless you restrict it. For safer workers:

• Give read-only tools to reviewers.
• Use permissionMode: plan for analysis agents.
• Use disallowedTools to remove risky capabilities.
• Scope MCP servers when the subagent only needs one external system.
• Use maxTurns for bounded background work.

This makes a subagent more like a specialist process than a vague prompt.

Worktree Isolation

For parallel edits, context isolation is not enough. You also need file isolation.

Set isolation: worktree on a custom subagent, or ask Claude to use worktrees for its agents:

---
name: test-fixer
description: Fixes isolated test failures without touching unrelated code.
tools: Read, Edit, Bash
isolation: worktree
---

Claude Code creates a temporary git worktree for the subagent. If the subagent makes no changes, the worktree can be cleaned up automatically. If it changes files, the worktree persists for review.

Nested Subagents

Current Claude Code supports nested subagents up to a fixed depth. Use this sparingly. It is useful when a delegated task itself splits into independent subtasks, such as a review subagent dispatching verifier subagents per finding.

Do not use nesting for routine work. It adds startup cost, token cost, and coordination overhead.

When Not to Use a Subagent

Stay in the main conversation when:

• The task needs frequent back-and-forth.
• Implementation and review share the same live context.
• The change is small and targeted.
• Latency matters more than context hygiene.

Use a skill instead when the main need is reusable instructions rather than context isolation.

Subagents vs Agent Teams

Subagents are your everyday parallelism tool. Agent teams are for heavier collaboration.

Subagents vs Dynamic Workflows

Use a subagent when you need one focused worker. Use a dynamic workflow when Claude should write an orchestration script and fan out across many agents with repeatable phases.

Official References

• Create custom subagents↗
• Run agents in parallel↗
• Dynamic workflows↗
• Run parallel sessions with worktrees↗