Learn to delegate complex tasks to parallel Claude Code instances, multiplying your capacity without increasing wait time.
One subagent is an independent instance of Claude Code launched by the main agent (orchestrator) to perform a specific task. It receives a well-defined prompt, runs with its own tools, and returns a summarized result.
The orchestrator uses the internal tool Task to create subagents. Each Task is isolated: it has its own conversation history, file context, and configured permissions.
The subagent doesn’t share memory with the orchestrator. It only knows what’s in the prompt it received. This is a feature — isolation ensures one subagent doesn’t contaminate another’s context.
Define the prompt with a clear scope, expected output format, and required permissions
A new isolated session is created with the prompt as its initial context
Uses Bash, Read, WebSearch, and other tools as needed
Text compressed with the output—not the full log, just the response
The quickest criterion: can you describe the task in 1–2 sentences with clear input and output? If so, it’s a candidate for a subagent. If it needs several paragraphs of context, run it in the orchestrator instead.
Fan-out is when an orchestrator launches N subagents simultaneously, each solving one part of the problem. The orchestrator remains blocked while waiting for them all to finish, then aggregates the results.
A search that would visit 8 sources in sequence (8 × 30s = 4 minutes) becomes 8 parallel subagents (~30 seconds). 8× speed at the same total cost.
You are the orchestrator. Use the Task tool to create 4 subagents in PARALLEL: Task 1: Research the official Claude Code documentation on hooks. Return: a list of available events with descriptions. Task 2: Read the project's .claude/settings.json files. Return: current configuration structure. Task 3: Research examples of hooks in public repositories. Return: 3 practical examples with code. Task 4: Analyze the code in src/ to identify opportunities for automation with hooks. Return: a prioritized list of improvements. // Wait for ALL of them to finish, then integrate the results.
Speed gains increase with N subagents, but so does cost. For tasks that take 1-2 minutes, fanning out to 4-8 agents is the sweet spot. Beyond 10 agents, coordination overhead reduces the return.
Read-only mode — access only to observation tools (Read, read-only Bash, WebSearch). It can't create or modify files.
Full access to tools — can read, write, run commands, and interact with external APIs.
Always use the most restrictive type the task allows. A research subagent with write permission is an unnecessary risk — if the model "hallucinates" an instruction, it could accidentally modify files.
A subagent's result reaches the orchestrator as plain text — a consolidated summary of what was found/done. The orchestrator receives no tool log, only the final response.
To ensure the result can be consumed, specify the output format in the prompt: Retorne: lista de bullets, Retorne: JSON com campos X e Y, etc.
Prompt do orquestrador: ~500 tokens ($0.003) Execução do subagent: ~2000 tokens ($0.012) Output para orquestrador: ~300 tokens ($0.002) ────────────────────── Total por subagent: ~$0.017 // Com prompt caching (se CLAUDE.md ou contexto fixo): Custo cache hit: ~$0.002 (10× mais barato) // ROI: 1h de trabalho humano = $50-100 // 100 subagents = $1.70 → 30× mais barato que humano
Compare: time saved × the value of your time vs API cost. If you save 1h ($50) and the automation costs $0.50, the ROI is 100×. This applies to any task you do more than once a week.
4.2 — 🪝 Hooks: automate the harness with PreToolUse, PostToolUse, SessionStart, and Stop