guide3 min read
Claude Code subagents: run work in parallel
One prompt, several agents working at the same time — each with its own fresh context window. Instead of Claude reading 40 files into one context until it gets sloppy, it spins up N subagents that each investigate a slice and report back a short answer. Faster, cleaner, and your main context stays uncluttered.
TL;DR: say "use subagents to…" and Claude fans the work out in parallel. Each subagent starts blank, does one self-contained task, and returns only its conclusion. Define custom agent types in
.claude/agents/<name>.md. They do not share memory — so every task must stand on its own.
How to invoke them
1. Just ask (natural language). The simplest trigger:
- "Use 3 subagents in parallel to review the auth, billing, and email modules."
- "Search the whole repo for every place we read
process.env— use subagents." - "Research these 5 libraries in parallel and give me a comparison table."
2. Via the Task / Agent tool. Under the hood Claude launches each subagent through its Task tool. You rarely call it by hand — the natural-language ask maps to it. When Claude sends several in one message, they run concurrently.
Custom agent types
Want a reusable specialist? Drop a file in .claude/agents/:
---
name: test-runner
description: >
Runs the test suite and diagnoses failures. Use proactively after code
changes, or when the user says "run the tests" or "why is this failing".
tools: Bash, Read, Edit, Grep
---
You are a focused test runner. When invoked:
1. Detect the runner (package.json scripts, pytest, go test…).
2. Run the full suite; capture failures.
3. For each failure, read the relevant file and propose the smallest fix.
4. Report: what failed, the root cause, and the fix. Be concise.
Frontmatter fields:
| Field | Purpose |
|---|---|
name |
how you refer to it: "use the test-runner agent" |
description |
when Claude should reach for it (same WHEN-focused rule as skills) |
tools |
optional allow-list; omit to inherit all tools |
Put it in <repo>/.claude/agents/ (team, committed) or ~/.claude/agents/ (personal).
When subagents shine
| Use case | Why parallel wins |
|---|---|
| Repo-wide search | 5 agents grep different dirs at once; you get one merged answer |
| Independent reviews | one agent per module → no cross-contamination, focused critiques |
| Parallel edits | apply the same refactor across unrelated files simultaneously |
| Research fan-out | compare libraries/APIs — one agent each, results in a table |
| Big context jobs | keep 200 files out of your main window; each agent digests its slice |
A concrete example
"Our API is slow. Use subagents: one to profile the DB queries in
/db, one to audit the N+1 risks in/services, one to check caching in/api. Each reports the top 3 issues it finds."
Three agents run at once, each reads only its area, and you get three tight lists back instead of one agent thrashing through the whole codebase.
Caveats (read these)
- No shared memory. Subagents can't see each other's work or your main conversation. Whatever an agent needs, put it in the task.
- Give each a self-contained brief. Goal + where to look + what to return. "Review the auth module" beats "review the thing we discussed."
- Ask for a conclusion, not a dump. You get the agent's final message, not its file reads — tell it to return a summary/table, not paste code.
- They can't ask you questions mid-run. Ambiguity = guessing. Be specific up front.
- More agents ≠ always better. For a single known-file lookup, one direct read is faster than spinning up an agent.
Where this fits
Reach for subagents the moment a task is wide (many files/topics) or splittable into independent chunks. Narrow, single-file work — just do it directly. The mental model: you're the lead, subagents are your team — delegate parallel work, keep the synthesis.
Guide by StackScout · more free AI-dev guides, skills & repo picks → stackscout.app
◎ free guides, every week
New setups like this land with each weekly drop. Get them the moment they ship:
Join the newsletter