Parallel AI: A Practical Guide to SubAgents in Claude Code

Most people use Claude Code as a single conversation — one question, one answer, one task at a time. That works for focused work. But some tasks are embarrassingly parallel: research twenty companies, review ten files, test five configurations, generate reports across multiple data sources. Doing these sequentially is like having twenty envelopes to mail and walking to the post office twenty times.

Claude Code has a subagent system that lets you run multiple AI tasks simultaneously — each with its own context, its own tool access, and its own output. In a recent project, we used twenty parallel subagents to research ninety companies across three stock indices in under fifteen minutes. Work that would have taken a full day sequentially.

This article covers how subagents actually work, when to use them, how to structure prompts that produce consistent results across parallel workers, and the patterns we have learned from using them in production.

What SubAgents Are

A subagent is an independent Claude Code instance that runs a specific task in the background. The parent agent — your main conversation — spawns it with a prompt and optional configuration, then continues working. The subagent runs autonomously, uses tools, reads and writes files, and returns its result when done.

Key properties:

• Independent context. Each subagent starts with its own conversation. It does not share memory with the parent or with other subagents.
• Full tool access. Subagents can read files, write files, run bash commands, use MCP servers — the same capabilities as the parent agent.
• Background execution. The parent does not block while subagents run. You can launch twenty subagents and continue working in the foreground.
• File-based coordination. Subagents write their output to files. The parent reads those files when the agents complete. There is no message-passing or shared state — the filesystem is the coordination layer.

┌─────────────────────────────────────────────┐
│              Parent Agent                    │
│                                              │
│  "Research these 20 companies"               │
│       │                                      │
│       ├── spawn ──► SubAgent 1 → company-a.md│
│       ├── spawn ──► SubAgent 2 → company-b.md│
│       ├── spawn ──► SubAgent 3 → company-c.md│
│       │   ...                                │
│       └── spawn ──► SubAgent 20→ company-t.md│
│                                              │
│  (continues working while agents run)        │
│                                              │
│  ← collect results when all complete         │
└─────────────────────────────────────────────┘

When to Use SubAgents

Not every task benefits from parallelism. The overhead of spawning a subagent — context initialization, tool discovery, prompt processing — means that very short tasks are faster done inline.

Good candidates for subagents:

• Independent research tasks. Researching companies, analyzing documents, reviewing files — where each unit of work has no dependency on the others.
• Bulk file operations. Generating reports, transforming data, creating documentation for multiple entities from a template.
• Multi-source data gathering. Pulling information from different MCP servers or web sources simultaneously.
• Parallel testing. Running the same test against multiple configurations or environments.

Poor candidates:

• Sequential work. If step 2 depends on step 1's output, subagents add overhead without benefit.
• Shared state. If multiple tasks need to read and write the same file, you get race conditions. The filesystem is not a database.
• Trivial tasks. If a task takes the agent 10 seconds inline, the spawning overhead makes a subagent slower, not faster.

The rule of thumb: if you can describe each task independently and the output is a separate file, subagents will help.

Structuring the Prompt

The most common mistake with subagents is vague delegation. A subagent starts with zero context — it does not know what the parent was doing, what files exist, or what the broader goal is. Everything it needs must be in the prompt.

The Three-Part Pattern

Every subagent prompt we write follows the same structure:

1. Context — what the agent needs to know before starting. 2. Task — exactly what to do. 3. Output — where to write the result and what format to use.

Bad prompt:

Research this company and write a report.

Good prompt:

You are researching companies for a B2B outreach campaign targeting
sustainability leaders in European enterprises.

Research the company "KBC Group" (https://www.kbc.com).
Find the following:
- Company overview (sector, headquarters, employee count, revenue)
- Key leadership (CEO, CTO, CSO or sustainability lead)
- Recent sustainability initiatives or ESG commitments
- Recent news (last 6 months)

Use web search and Playwright for website navigation if needed.

Write your findings to /path/to/companies/kbc-group.md using this structure:
# KBC Group
## Overview
## Leadership
## Sustainability
## Recent News
## Sources

The good prompt is self-contained. The subagent can execute it without any additional context.

Consistency Across Agents

When you spawn twenty subagents to do the same type of work, consistency matters. If each agent structures its output differently, the parent — or the human reviewing the results — has to normalize everything afterward.

The fix is a template in the prompt. Specify the exact markdown structure, the sections, and what goes in each section. Every agent follows the same template, producing uniform output that is easy to aggregate.

Real Examples

Marketing Pipeline — 20 Agents, 90 Companies

In From Stock Index to Sales Pipeline, we researched ninety companies across three European stock indices. The workflow:

1. Parent agent builds a CSV of companies from the BEL-20
2. Parent spawns 20 subagents — one per company — each with the three-part prompt
3. Parent continues to build the AEX company list while BEL-20 agents run
4. When BEL-20 agents complete, parent spawns 30 more for AEX
5. Then 40 more for CAC 40

Total research time: ~15 minutes. Sequential equivalent: 6-8 hours.

The key insight: the parent agent is not idle while subagents run. It can do preparatory work for the next batch, or handle a completely different task.

Ignition CLI Development — Parallel Testing

When building the Ignition CLI, we used subagents to test command groups in parallel. One agent tests gateway commands, another tests tag commands, another tests project commands — all against the same live gateway simultaneously. Each agent writes a test report, and the parent aggregates the results.

This pattern works for any CLI or API verification: define the test scope per agent, let them run independently, collect the results.

Code Review Across Modules

For large codebases, a single code review pass takes long and loses focus. Instead, spawn one subagent per module or file group. Each agent reviews its scope, writes findings to a review file, and the parent compiles a summary. The reviews run in parallel, and each agent maintains focus on a smaller scope — producing better results than a single exhaustive pass.

Background vs Foreground

Claude Code supports two execution modes for subagents:

Foreground — the parent waits for the result before continuing. Use this when you need the output immediately to inform the next step.

Background — the parent continues working while the agent runs. Use this for independent tasks where you do not need the result right away.

In practice, most parallel workloads use background agents. The parent launches them all, optionally does other work, and then processes results when agents complete.

Worktree Isolation

For tasks that modify files — refactoring, code generation, large edits — Claude Code can run subagents in isolated Git worktrees. Each agent gets its own copy of the repository. Changes made by one agent do not affect others or your working directory.

This is essential when:

• Multiple agents need to edit the same files differently (e.g., testing two approaches)
• You want to review changes before merging them into your working tree
• Agents are doing experimental or destructive work that you might want to discard

Without worktree isolation, two background agents writing to the same file will corrupt each other's work.

Practical Limits

Concurrency. Claude Code manages its own concurrency limits. In practice, 20 simultaneous subagents works well. Beyond that, diminishing returns — API rate limits become the bottleneck.

Context per agent. Each subagent has its own context window. Long-running agents with many tool calls can hit context limits just like a regular conversation. Keep tasks focused — one clear objective per agent.

Cost. Every subagent is a separate API conversation. Twenty subagents each using 10K tokens is 200K tokens total. The parallelism trades time for cost — make sure the time savings justify the spend.

Error handling. Subagents can fail — network errors, tool failures, rate limits. The parent agent can check for completion and retry or report failures. Build this into your workflow rather than assuming all agents succeed.

Getting Started

Start small. Pick a task you currently do sequentially — reviewing a set of files, researching a list of items, generating reports — and restructure it as parallel work:

1. Define the unit of work. What is one independent task?
2. Write the three-part prompt. Context, task, output — fully self-contained.
3. Test with one agent. Verify the output is what you expect before scaling.
4. Scale to N agents. Launch the full batch and collect results.

The progression from "one agent, one task" to "twenty agents, twenty tasks" is where Claude Code stops being a chat tool and becomes an execution platform.

---

For hands-on practice with these techniques, see the Claude Code Workflows specialization. For the business context — what this looks like applied to real marketing, research, and engineering workflows — see From Stock Index to Sales Pipeline and Why VS Code Is the Only AI Workbench Your Company Needs.