How do I launch a sub-agent in Claude Code?

Use the Agent tool with a prompt describing the task. The key parameters are: subagent_type (which specialized agent to use — 'Explore' for read-only search, 'Plan' for design, 'claude' as catch-all), prompt (self-contained task description — the sub-agent has no memory of the parent conversation), and optionally isolation: 'worktree' (auto-creates a git worktree for the sub-agent to work in, preventing branch contamination). Example: Agent({description: 'Find auth middleware', subagent_type: 'Explore', prompt: 'Locate all files that implement authentication middleware in this repo. Report file paths and key function names.'}).

What is the difference between foreground and background sub-agents?

Foreground sub-agents (default) block the orchestrator until they return — use these when you need the result before proceeding. Background sub-agents (run_in_background: true) let the orchestrator continue with other work while the agent runs; you are notified when it completes. Use background agents for genuinely independent tasks — e.g., spawning a test-runner while writing new code. Do NOT background-poll a sub-agent you started with run_in_background=true; wait for the automatic completion notification instead.

What are the available sub-agent types (subagent_type)?

Built-in agent types: 'Explore' (fast read-only search — good for finding files, grepping symbols, answering 'where is X defined'; reads excerpts so do NOT use for deep code review), 'Plan' (software architect agent for designing implementation plans; returns step-by-step plans and identifies critical files), 'claude' (general-purpose catch-all; has access to all tools). Custom agent types can be defined in a project's agent registry. If you omit subagent_type, the general-purpose agent is used.

What is isolation: 'worktree' in sub-agents?

When you pass isolation: 'worktree', Claude Code automatically creates a temporary git worktree (a separate checkout of the repo on a new branch) for the sub-agent to work in. This prevents the sub-agent's changes from conflicting with your main branch or other sub-agents. If the agent makes no changes, the worktree is automatically cleaned up. If it does make changes, the worktree path and branch are returned so the orchestrator can review and merge them. Use worktree isolation for any sub-agent that writes code.

How do I write a good sub-agent prompt?

The golden rule: the sub-agent has NO memory of the parent conversation. Every prompt must be fully self-contained. Include: (1) What you're trying to accomplish and why. (2) What you've already ruled out. (3) File paths, line numbers, or function names if known. (4) The specific output format you expect. (5) How long the response should be ('report in under 200 words' for research, no limit for code tasks). Terse prompts produce shallow results — brief the sub-agent like a colleague walking into the room cold.

Can sub-agents call other sub-agents (nested agents)?

Yes — sub-agents can themselves use the Agent tool to spawn further sub-agents, creating a tree of agents. In practice, keep nesting shallow (1-2 levels) to avoid runaway token costs and hard-to-debug execution chains. A common pattern: orchestrator → Explore agent (finds relevant files) → claude agent (rewrites each file). The orchestrator waits for the Explore result, then fans out to parallel write agents, then collects results.

What tasks benefit most from sub-agents?

Best fits: (1) Parallel file analysis — 'summarize each of these 10 modules' across 10 simultaneous agents. (2) Independent code generation — writing tests for 5 separate functions simultaneously. (3) Research + implementation split — Explore agent finds the right files, then a write agent acts on them without re-reading. (4) Multi-repo tasks — one agent per repo, all in isolated worktrees. (5) Code review vs implementation — Plan agent designs it, claude agent builds it. Poor fits: tasks with tight sequential dependencies, or single-file edits where spawning overhead outweighs the benefit.

Claude Code Sub-Agents

Multi-agent orchestration: spawn parallel worker agents, isolate work in git worktrees, and run specialized sub-agents concurrently.

What are sub-agents?

Sub-agents are independent Claude instances that the main (orchestrator) agent spawns via the Agent tool. Each sub-agent runs with its own context window, can call tools, read files, write code, and return a result. They enable true parallel execution — instead of working sequentially through a 10-file refactor, an orchestrator can dispatch 10 sub-agents simultaneously and collect all results in one pass.

Sub-agents are available in Claude Code's SDK/API layer and in the interactive CLI when Claude uses the Agent tool internally. You can also direct Claude to use them explicitly by describing your task in terms of parallel sub-tasks.

Key insight: The sub-agent has zero memory of the parent conversation. Every prompt must be fully self-contained — file paths, context, expected output format, everything. This is the most common mistake when working with sub-agents.

The Agent Tool

Claude Code orchestrators invoke sub-agents via the Agent tool. Core parameters:

Parameter	Required	Description
`description`	Yes	3–5 word summary of what the agent will do (shown in UI)
`prompt`	Yes	Fully self-contained task description. No conversation history is passed.
`subagent_type`	No	Which specialized agent to use (see types below). Defaults to general-purpose.
`run_in_background`	No	If `true`, orchestrator continues immediately; notified on completion.
`isolation`	No	`"worktree"` — auto-creates a git worktree for the agent to write into.

Example: parallel file analysis

# Orchestrator spawns 3 sub-agents simultaneously (one message, multiple Agent calls):

Agent({
  description: "Analyze auth module",
  subagent_type: "Explore",
  prompt: "Read src/auth/middleware.ts and src/auth/session.ts. Report: what does each file export, what are the key function signatures, and are there any obvious security issues? Under 150 words."
})

Agent({
  description: "Analyze payments module",
  subagent_type: "Explore",
  prompt: "Read src/payments/stripe.ts and src/payments/webhook.ts. Report: what does each file export, what are the key function signatures, and are there any obvious security issues? Under 150 words."
})

Agent({
  description: "Analyze users module",
  subagent_type: "Explore",
  prompt: "Read src/users/model.ts and src/users/service.ts. Report: what does each file export, what are the key function signatures, and are there any obvious security issues? Under 150 words."
})

Specialized Agent Types

Explore Fast read-only search agent. Finds files by pattern, greps for symbols, answers "where is X defined." Reads excerpts — do NOT use for full code review or cross-file consistency checks.

Plan Software architect agent. Designs implementation plans, identifies critical files, considers architectural trade-offs. Returns step-by-step plans. Cannot write files.

claude (general-purpose) All-tools catch-all. Use when the task involves writing code, editing files, running commands, or anything not covered by a specialized type.

Custom agent types can be registered in a project's agent configuration. Third-party skill packs may also add agent types (e.g., code-reviewer, security-auditor).

Foreground vs Background Execution

Foreground (default)

The orchestrator blocks until the sub-agent returns. Use this whenever you need the result before proceeding — research agents whose findings inform next steps, or any agent whose output you'll immediately act on.

Background (`run_in_background: true`)

The orchestrator continues immediately; you are auto-notified when the agent completes. Use background when you have genuinely independent work to do in parallel — writing new code while a test-runner agent validates existing code, for example.

Do NOT poll background agents. If you start an agent with run_in_background: true, wait for the automatic completion notification. Polling loops waste tokens and add latency.

# Background agent — orchestrator continues while this runs
Agent({
  description: "Run full test suite",
  run_in_background: true,
  prompt: "Run 'npm test' and report: total tests, failures, and any error messages. Under 100 words."
})

# Orchestrator now continues writing new feature code...
# Will be notified when test agent completes.

Worktree Isolation

Pass isolation: "worktree" to have Claude Code automatically create a temporary git worktree for the sub-agent. This gives the agent its own branch and directory — changes won't conflict with your main working tree or other sub-agents.

If the agent makes no changes, the worktree is cleaned up automatically.
If the agent makes changes, the worktree path and branch name are returned so you can review and merge.
Essential for parallel write agents — without isolation, two agents editing the same file simultaneously will corrupt each other's work.

# Two agents write to separate files simultaneously, safely isolated
Agent({
  description: "Add user auth tests",
  isolation: "worktree",
  prompt: "In this repo, add unit tests for src/auth/middleware.ts. Create tests/auth/middleware.test.ts with at least 5 test cases covering: valid JWT, expired JWT, missing token, malformed token, and role-based access. Use the existing test patterns from tests/users/model.test.ts."
})

Agent({
  description: "Add payments tests",
  isolation: "worktree",
  prompt: "In this repo, add unit tests for src/payments/stripe.ts. Create tests/payments/stripe.test.ts with at least 5 test cases. Use the existing test patterns from tests/users/model.test.ts."
})

Writing Effective Sub-Agent Prompts

The sub-agent starts cold — no history, no context from the parent session. Terse prompts produce shallow results.

What to always include

Goal + why it matters — "We're adding rate limiting to the API because our current endpoint has no throttling."
What you've already ruled out — "We tried express-rate-limit but it doesn't work with our Redis cluster setup."
Specific file paths and line numbers — "The relevant file is src/api/middleware.ts, specifically the authenticate() function at line 42."
Expected output format — "Report file paths and function names only, under 200 words" for research; no limit for code tasks.
Constraints — "Do not modify package.json or any test files."

What to never do

Reference "the conversation" or "what we discussed earlier" — the agent has no access to that.
Say "based on your findings, fix the bug" in a follow-up — that's synthesis you must do yourself before writing the next prompt.
Write terse one-line prompts for complex tasks — you'll get a generic result.

Common Orchestration Patterns

Fan-out / fan-in

Orchestrator dispatches multiple parallel sub-agents, waits for all to return, then synthesizes results. Best for: parallel file analysis, multi-repo tasks, batch code generation.

# Step 1: Fan-out (all 3 run in parallel)
results = [
  Agent({description:"Audit auth", prompt:"..."}),
  Agent({description:"Audit payments", prompt:"..."}),
  Agent({description:"Audit users", prompt:"..."})
]

# Step 2: Orchestrator synthesizes results and decides next action
# Step 3: Fan-out again with write agents if changes needed

Research then implement

An Explore agent finds the right files first. The orchestrator reads the result, identifies what to change, then sends specific write instructions to a claude agent. Avoids the write agent scanning the entire repo.

Design then build

A Plan agent designs the architecture and returns a step-by-step plan. The orchestrator reviews it (and possibly asks the user to confirm), then dispatches build agents per the plan.

Independent background work

Start a test-runner or lint agent in the background while continuing to write code. Merge the test results when they arrive.

Cost Considerations

Each sub-agent is a full Claude API call with its own context. Costs multiply with agent count. Tips to keep costs down:

Use the Explore type (not general-purpose) for read-only research — it's optimized to read less.
Keep sub-agent prompts specific — "read src/auth/middleware.ts and report exports" costs far less than "explore the auth system."
Set explicit response-length limits for research agents: "under 200 words."
Don't nest agents more than 2 levels deep — the token tree grows exponentially.
For batch file edits, prefer one agent per file over one agent per function.

FAQ

Do sub-agents have access to the same tools as the main agent?

Specialized types have restricted tool sets (Explore is read-only; Plan cannot write files). General-purpose claude agents have access to all tools. Tool permissions from your Claude Code settings still apply.

Can I use sub-agents in the interactive Claude Code CLI?

Claude Code's orchestrator uses the Agent tool internally when it decides to delegate work. In some contexts you can directly instruct Claude to use it. Sub-agents are most commonly used when building automated pipelines with Claude Code SDK.

How do I debug a sub-agent that returns a bad result?

The most common cause is an under-specified prompt. Add more context, file paths, and constraints. If the agent is calling wrong tools, use a more specific subagent_type. If results look like hallucinations, the agent likely couldn't find the files — add explicit paths and verify they exist before dispatching.

How many sub-agents can run in parallel?

No hard limit is enforced in the framework. In practice, 3–8 parallel agents is efficient; beyond that you're likely waiting on the slowest agent anyway. Rate limits on your API tier apply per-request, so very wide fan-outs may hit throttling.

What happens if a sub-agent fails or times out?

The Agent tool call returns an error result to the orchestrator. The orchestrator should check the result and either retry with a different prompt, try a simpler approach, or surface the error to the user. Don't silently ignore failed sub-agent calls.

Are sub-agents the same as Claude Code worktrees?

Related but different. Worktrees are a git feature that lets you check out multiple branches simultaneously — useful for running parallel Claude Code sessions manually. Sub-agents with isolation: "worktree" use git worktrees under the hood to isolate automated agent work, but the agent-spawning itself is a separate concept.

Related Guides

Worktrees & Parallel Agents — run multiple Claude Code sessions on isolated branches
Automation with /loop — recurring agents and interval-based tasks
GitHub Actions & CI/CD — headless Claude Code in automated pipelines
Best Practices — CLAUDE.md, permissions, context management, and cost tips
Claude Code Hooks — event-triggered shell commands for automation
All Claude Code Skills — full directory

Claude Code Sub-Agents

What are sub-agents?

The Agent Tool

Example: parallel file analysis

Specialized Agent Types

Foreground vs Background Execution

Foreground (default)

Background (run_in_background: true)

Worktree Isolation

Writing Effective Sub-Agent Prompts

What to always include

What to never do

Common Orchestration Patterns

Fan-out / fan-in

Research then implement

Design then build

Independent background work

Cost Considerations

FAQ

Do sub-agents have access to the same tools as the main agent?

Can I use sub-agents in the interactive Claude Code CLI?

How do I debug a sub-agent that returns a bad result?

How many sub-agents can run in parallel?

What happens if a sub-agent fails or times out?

Are sub-agents the same as Claude Code worktrees?

Related Guides

More Claude Code Tools

Background (`run_in_background: true`)