Claude Code Subagents: Running Parallel AI Tasks

How to use Claude Code subagents to run parallel AI tasks. Complete guide with examples for spawning subagents, passing context, and aggregating results.

Claude Code subagents let you break a large task into parallel workstreams. Instead of one sequential session handling 10 files one at a time, you spawn 10 subagents that work concurrently and report back. This guide shows the patterns that work in production.

Basic subagent spawn (SDK)

import anthropic

client = anthropic.Anthropic()

# Parent spawns a subagent by calling the API with a focused task
def run_subagent(task: str, context: str) -> str:
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=2048,
        system="You are a code analysis subagent. Be concise and structured.",
        messages=[
            {"role": "user", "content": f"Context:
{context}

Task: {task}"}
        ]
    )
    return response.content[0].text

Parallel subagents with ThreadPoolExecutor

from concurrent.futures import ThreadPoolExecutor, as_completed
import anthropic

client = anthropic.Anthropic()

FILES = ["auth.py", "payments.py", "users.py", "orders.py", "notifications.py"]

def audit_file(filepath: str) -> dict:
    with open(filepath) as f:
        code = f.read()
    response = client.messages.create(
        model="claude-haiku-4-5-20251001",  # Haiku for cost efficiency
        max_tokens=512,
        messages=[{
            "role": "user",
            "content": f"List any SQL injection or auth bypass risks in this file. File: {filepath}

{code}"
        }]
    )
    return {"file": filepath, "issues": response.content[0].text}

# Run all 5 audits in parallel
with ThreadPoolExecutor(max_workers=5) as executor:
    futures = {executor.submit(audit_file, f): f for f in FILES}
    results = []
    for future in as_completed(futures):
        results.append(future.result())

# Aggregate: parent session synthesizes all subagent outputs
all_issues = "

".join(f"## {r['file']}
{r['issues']}" for r in results)

summary = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": f"Summarize the top 5 security risks across these audit results:

{all_issues}"
    }]
)
print(summary.content[0].text)

Subagents with prompt caching (for shared context)

import anthropic
from concurrent.futures import ThreadPoolExecutor

client = anthropic.Anthropic()

# Large shared spec loaded once, cached across all subagent calls
SPEC = open("api-spec.md").read()  # e.g. 50K tokens

def generate_endpoint_handler(endpoint: str) -> str:
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=2048,
        system=[{
            "type": "text",
            "text": f"You generate Python FastAPI handlers. Follow this spec:

{SPEC}",
            "cache_control": {"type": "ephemeral"}  # cache the spec
        }],
        messages=[{
            "role": "user",
            "content": f"Generate the handler for: {endpoint}"
        }]
    )
    return response.content[0].text

ENDPOINTS = [
    "POST /users/register",
    "POST /users/login",
    "GET /users/{id}",
    "PUT /users/{id}",
    "DELETE /users/{id}",
]

with ThreadPoolExecutor(max_workers=5) as pool:
    handlers = list(pool.map(generate_endpoint_handler, ENDPOINTS))

# handlers[0] = POST /users/register handler code, etc.
# Spec cached after first call → 90% cheaper for calls 2–5

Cost per subagent pattern

Subagent patterns in Claude Code CLI

# Claude Code CLI's Agent tool spawns subagents automatically
# when you use /agents or when the task prompt includes parallel work.

# Explicit parallel task (Claude Code decides to fan out):
claude "Review all Python files in src/ for security issues and summarize"
# Claude Code will spawn subagents for large file sets automatically

# Force headless parallel processing with bash:
for f in src/*.py; do
  claude --print "Audit $f for SQL injection" > "audit_$(basename $f).txt" &
done
wait  # run all in parallel, collect outputs

For cost estimation across your subagent workflow, use claude-cost-calc.vercel.app. For a full guide to multi-agent patterns with the Claude API, see the Claude API Cookbook.

Frequently asked questions

Free tools

More examples