Claude Code Multi-Agent & Subagents: Run Parallel AI Tasks Like a Pro

Table of Contents

⏱ Reading time: ~12 min | 🗓 Updated: June 2026

One of the most powerful — and least understood — features of Claude Code is its multi-agent architecture. While most developers use Claude Code as a single AI session working through tasks sequentially, the platform supports spawning multiple subagents that work in parallel, each with its own isolated context, tool access, and git worktree. The result can be 3×–5× throughput for the right class of tasks.

Searches for “Claude Code subagents” have grown over 600% in Q2 2026 according to Google Trends, reflecting the developer community’s rapid adoption of parallel AI workflows. This guide covers everything: how subagents work, when to use them, how to orchestrate them, and the patterns that experienced teams are using to 3× their AI coding output.

How Claude Code’s Agent Architecture Works

Claude Code operates in what Anthropic calls an agent loop: Claude receives a task, reasons about it, calls tools (read file, write file, run bash, search web), observes results, and continues until the task is complete. By default, this is a single-threaded loop — one step at a time.

Subagents break this constraint. The orchestrator (main Claude instance) can spawn one or more subagent instances using the Task tool. Each subagent:

Runs in its own isolated process with its own context window
Can have its own git worktree (so multiple agents can edit files without conflicts)
Has access to all the same tools as the orchestrator
Reports results back to the orchestrator when complete
Can itself spawn further subagents (recursive spawning, as of June 2026)

The Orchestrator-Worker Pattern

The standard pattern is an orchestrator-worker topology:

Orchestrator: Plans the overall task, breaks it into independent subtasks, spawns workers, collects and merges results
Workers: Execute a specific subtask in isolation, report results back to the orchestrator

This works best when subtasks are independent — they don’t need to read each other’s in-progress output. Examples: running tests on different modules, implementing different features on separate branches, researching different API documentations simultaneously.

The Five Ways Claude Code Runs Multi-Step Work

Mode	Description	Best For
Single agent (default)	One Claude instance, sequential steps	Most tasks, dependent steps
Subagents (Task tool)	Orchestrator spawns worker subagents	Independent parallel subtasks
Agent view	Visual panel showing active agents	Monitoring parallel workloads
Agent teams	Pre-configured multi-agent setups	Repeatable team workflows
Dynamic workflows	Agents spawn agents based on task needs	Complex, adaptive workloads

Setting Up Git Worktrees for Parallel Agents

The key to avoiding file conflicts between parallel subagents is git worktrees. A worktree lets you check out multiple branches of the same repository into different directories simultaneously. Each subagent gets its own worktree and branch:

# Create worktrees for parallel agent work
git worktree add ../project-agent-1 -b feature/agent-1
git worktree add ../project-agent-2 -b feature/agent-2
git worktree add ../project-agent-3 -b feature/agent-3

# Verify worktrees
git worktree list

# After agents complete, merge results
git checkout main
git merge feature/agent-1
git merge feature/agent-2
git merge feature/agent-3

# Clean up worktrees
git worktree remove ../project-agent-1
git worktree remove ../project-agent-2
git worktree remove ../project-agent-3

When to Use Subagents: The Decision Framework

Subagents are not always the right choice. Use this decision framework:

USE Subagents When:

✅ Tasks are clearly independent (no shared state between subtasks)
✅ Each subtask takes 10+ minutes for a single agent (parallelism worth the overhead)
✅ You have multiple modules/services that can be worked on simultaneously
✅ You’re doing research across multiple sources that don’t depend on each other
✅ Running a comprehensive test suite across independent test modules

DON’T USE Subagents When:

❌ Tasks have sequential dependencies (step 2 needs step 1’s output)
❌ Tasks are fast (<5 minutes) — spawning overhead isn’t worth it
❌ Tasks involve shared mutable state that agents would conflict over
❌ You need real-time coordination between agents mid-task

Practical Subagent Workflow Examples

Example 1: Parallel Feature Implementation

You need to implement 4 independent features for a sprint. Instead of sequentially spending 2 hours per feature (8 hours total), spawn 4 subagents in parallel:

# CLAUDE.md orchestrator instruction example:
# Task: Implement sprint features in parallel

# The orchestrator would issue this plan:
Subtask 1 (Agent 1, worktree: feature/user-auth):
  Implement JWT authentication middleware
  Files: src/middleware/auth.ts, src/types/jwt.ts
  Tests: tests/middleware/auth.test.ts

Subtask 2 (Agent 2, worktree: feature/payment-api):
  Implement Stripe payment integration
  Files: src/services/payment.ts, src/routes/payment.ts
  Tests: tests/services/payment.test.ts

Subtask 3 (Agent 3, worktree: feature/email-service):
  Implement SendGrid email service
  Files: src/services/email.ts, src/templates/
  Tests: tests/services/email.test.ts

Subtask 4 (Agent 4, worktree: feature/analytics):
  Add PostHog analytics tracking
  Files: src/utils/analytics.ts, src/hooks/useAnalytics.ts
  Tests: tests/utils/analytics.test.ts

# All 4 run in parallel, then orchestrator merges

Example 2: Parallel Code Review + Security Scan

# Parallel review workflow
Orchestrator prompt:
"Review the PR diff in diff.patch. Spawn 3 subagents:
  Agent 1: Review for correctness and logic errors
  Agent 2: Review for security vulnerabilities (OWASP Top 10)
  Agent 3: Review for performance issues and N+1 queries
Collect all findings and produce a unified review report."

Example 3: Parallel Documentation Generation

# Documentation parallelization
Orchestrator prompt:
"Generate API documentation for all modules in src/. 
Spawn one subagent per module directory:
  Agent 1: src/auth/ -> docs/api/auth.md
  Agent 2: src/payments/ -> docs/api/payments.md
  Agent 3: src/users/ -> docs/api/users.md
  Agent 4: src/notifications/ -> docs/api/notifications.md
Each agent should read all files in its module and generate
complete API documentation with examples."

Example 4: Parallel Test Suite Execution

# Parallel testing with result aggregation
Orchestrator prompt:
"Run the full test suite in parallel. Spawn 4 subagents:
  Agent 1: Run unit tests (npm test -- --testPathPattern=unit)
  Agent 2: Run integration tests (npm test -- --testPathPattern=integration)
  Agent 3: Run E2E tests (npx playwright test)
  Agent 4: Run performance benchmarks (npm run benchmark)
Report all failures with context. Stop if unit tests fail —
no need to run other suites if fundamentals are broken."

Configuring Subagents via CLAUDE.md

You can give your orchestrator Claude explicit instructions about when and how to spawn subagents in your CLAUDE.md file:

# CLAUDE.md — Multi-Agent Configuration

## Parallelization Policy

When working on tasks that span multiple independent modules,
ALWAYS spawn subagents rather than working sequentially.

Module boundaries for this project:
- src/auth/ — authentication and authorization
- src/api/ — REST API routes and controllers
- src/db/ — database models and migrations
- src/ui/ — React components and pages
- tests/ — test suites

## Worktree Convention
Each subagent should use a separate worktree:
- Naming: feature/agent-{task-name}
- Base branch: always branch from main
- After completion: report changes for orchestrator to merge

## Orchestrator Instructions
- Break features into module-level subtasks when possible
- Never let two agents touch the same files
- Always run tests within each agent before reporting completion
- Collect all results before presenting to user

Agent View: Monitoring Parallel Work

Claude Code’s Agent View (available via the /agents command or the agent panel in Claude.ai) provides a real-time dashboard of all active subagents, their current status, recent actions, and output. Think of it as a process monitor for your AI workers.

Key capabilities in Agent View:

See all active agents and their current task
Monitor token usage per agent (to manage costs)
Kill a misbehaving agent without affecting others
View the message history of any individual agent
Promote a subagent output to the main session

Cost Management for Multi-Agent Workloads

Parallel agents means parallel token consumption. Here’s how to keep costs manageable:

Strategy	Description	Typical Savings
Narrow task scope	Give each agent only the files it needs to read	30-50% token reduction
Use Sonnet for workers	Reserve Opus 4.5 for orchestrator; use Sonnet 4.5 for workers	60-70% cost reduction
Summarize before spawn	Have orchestrator summarize context before passing to workers	20-40% reduction
Limit parallelism	Cap at 3-4 simultaneous agents instead of 8+	Proportional to agents
Early termination	Kill agents immediately when they report completion	5-15% reduction

Real-World Performance Results

Based on community reports from developers using Claude Code multi-agent workflows in production (Q2 2026):

Feature sprints: Teams report completing 4-week feature sprints in 1.5-2 weeks using parallel agents for independent features
Test generation: Generating tests for an entire codebase: from 8 hours sequential to 2.5 hours parallel (4 agents)
Documentation: Full API docs for 20-module project: from 6 hours to 90 minutes (8 agents, one per module)
Code review: Comprehensive PR reviews (security, performance, correctness): from 45 minutes to 15 minutes (3 specialized agents)

Common Pitfalls and How to Avoid Them

1. Race Conditions on Shared Files

Problem: Two agents both try to modify package.json or a shared config file, causing merge conflicts.
Fix: Explicitly list shared files in CLAUDE.md as “orchestrator-only” files that subagents must not touch. Agents should report what dependencies they need; the orchestrator handles all shared file writes.

2. Context Pollution

Problem: You pass too much context to subagents, causing them to spend tokens reading irrelevant files.
Fix: Give each subagent a precise file list: “You have access to src/auth/ and tests/auth/ only. Do not read other directories.”

3. Runaway Agent Costs

Problem: A subagent gets stuck in a loop, consuming tokens without making progress.
Fix: Set explicit step budgets in subagent instructions (“Complete this task in no more than 20 tool calls”) and monitor via Agent View. Kill and restart stuck agents.

4. Merge Conflicts at Integration

Problem: Agents worked on “independent” tasks but their changes conflict at merge time.
Fix: Before spawning, have the orchestrator do a file-level dependency analysis: list every file each subtask will touch and verify there’s no overlap.

Conclusion

Claude Code’s multi-agent architecture is one of the most powerful tools in a modern developer’s toolkit. When used correctly — for genuinely independent parallel tasks with proper worktree isolation — it can deliver 3×–5× throughput compared to sequential single-agent workflows.

Start small: pick one workflow (like parallel PR review or parallel test generation) and run two agents in parallel. Get comfortable with git worktrees, monitor costs via Agent View, and gradually build up to more complex multi-agent orchestrations. The official agents documentation is the best reference for all available options and configurations.