Run multiple sub-agents in parallel instead of sequentially.

What it is

Sub-agents are independent Claude instances with their own context. The main agent orchestrates, the sub-agents do the actual work in parallel. Result: split complex tasks, run them at the same time, and keep the main context clean and cheap.

Install / Setup

Sub-agents are built into Claude Code (Task tool / sub-agent tool) — nothing to install. You just need the right instruction so Claude actually uses them.

Option 1 — CLAUDE.md rule:

## Sub-agents (IMPORTANT — ALWAYS use)
- Default is a sub-agent — anything beyond a quick Grep/Edit
- Code changes → sub-agent reads, understands, edits. Main context stays clean.
- Multi-file edits → multiple sub-agents in parallel
- Research → sub-agent
- Main context only for: planning, decisions, short status updates
- Parallelize — fire independent sub-agents at the same time, not one after another

Option 2 — Prompt Claude Code:

Add a sub-agent strategy to my ~/.claude/CLAUDE.md: default is sub-agent for anything beyond a quick Grep/Edit, multi-file edits in parallel, main context only for planning/decisions. Check first if there's already something about sub-agents and merge cleanly.

Or ad-hoc in chat:

Fire off 3 parallel sub-agents: one documents all API routes, one checks the DB schemas, one reviews the tests. Summarize the results for me.

Use cases

• Multi-file refactor — 5 sub-agents edit one file each in parallel instead of 10 minutes sequentially.
• Codebase recon — A sub-agent "grep + read + understand" hands you a focused result and keeps your main context empty.
• Competitor analysis — 3 sub-agents analyze 3 competitor sites at once.
• Test generation for a whole module — One sub-agent per file writing tests, main agent reviews.
• Docs for a big system — Parallel sub-agents, one per subsystem.

Pro tip

Every sub-agent burns tokens. Don't fire one off for every tiny task. Rule of thumb: if the task is a clearly scoped research/edit with a structured output — sub-agent. If you're steering and deciding the whole time — main context.

🚀 Inside the community we build complete automation systems and workflows that actually run your day. → Join the Claude Code Mastery Community

Updated regularly — follow @vine.codes for more.