Parallel Agents

Parallel Agents Orchestration

Goal

Decompose complex tasks into independent sub-tasks and run them in parallel via specialized sub-agents to maximize efficiency.

When to use parallelism

┌──────────────────────────────────────────────────────────────────┐
│                   DECISION: PARALLEL OR SEQUENTIAL ?              │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│  PARALLEL if:                                                     │
│  - INDEPENDENT sub-tasks (no data dependency)                    │
│  - MERGEABLE results (combinable without conflict)               │
│  - Task DECOMPOSABLE into distinct parts                         │
│                                                                   │
│  SEQUENTIAL if:                                                   │
│  - Result A required to start B                                  │
│  - Modifications on the SAME files                               │
│  - Execution order MATTERS                                       │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘

Parallelization patterns

1. Fan-Out / Fan-In

         ┌─→ [Agent A: security audit] ─→┐
         │                                 │
[Task]  ─┼─→ [Agent B: perf audit]     ─→┼─→ [Combined report]
         │                                 │
         └─→ [Agent C: a11y audit]     ─→┘

Usage: Audits, multi-criteria analyses, parallel reviews

2. Map-Reduce

[Files] ─→ [Agent 1: file A] ─→┐
        → [Agent 2: file B] ─→┼─→ [Synthesis]
        → [Agent 3: file C] ─→┘

Usage: Code analysis by module, tests by domain

3. Pipeline with parallel steps

[Step 1] ─→ [Step 2a] ─→┐
            [Step 2b] ─→┼─→ [Step 3]
            [Step 2c] ─→┘

Usage: Build pipeline, workflow with independent steps

Common parallelizable tasks

Audits and analyses

Development

Business

How to dispatch

Step 1: Decompose the task

## Main task: [Description]

### Identified sub-tasks:
1. [ ] [Sub-task A] - Agent: [type] - Independent: Yes/No
2. [ ] [Sub-task B] - Agent: [type] - Independent: Yes/No
3. [ ] [Sub-task C] - Agent: [type] - Independent: Yes/No

### Dependencies:
- A → independent
- B → independent
- C → depends on A and B

### Plan:
- Phase 1 (parallel): A + B
- Phase 2 (sequential): C (after A and B)

Step 2: Launch in parallel

Use the Task tool with multiple calls in a single message:

[Call 1] Task(subagent_type="qa-security", prompt="Audit...")
[Call 2] Task(subagent_type="qa-perf", prompt="Analyze...")
[Call 3] Task(subagent_type="wcag-audit", prompt="Verify...")

Step 3: Combine results

## Combined report

### Agent A: [Summarized results]
### Agent B: [Summarized results]
### Agent C: [Summarized results]

### Synthesis
[Overview and priorities]

File conflict prevention

IMPORTANT: Parallel agents editing the same files cause race conditions and broken builds.

Before parallelizing, establish a file map

### Files per agent:
- Agent A: src/auth/ (exclusive)
- Agent B: src/api/ (exclusive)
- Agent C: src/utils/helpers.ts (CONFLICT with A and B!)

→ Solution: Agent C sequential after A and B

File-locking rules

Typically shared files (caution)

• package.json — deps added by multiple agents
• tsconfig.json — paths modified
• src/index.ts — exports added
• .env.example — variables added
• Routing/navigation files

Best practices

• Verify the independence of sub-tasks BEFORE parallelizing
• Establish the map of files modified per agent BEFORE launching
• Give each agent a clear and bounded scope
• Use run_in_background: true for long tasks
• Combine results with a high-level synthesis
• Limit to 3-5 parallel agents for readability
• Prefer isolation: "worktree" for agents that edit many files

Native Agent Teams (recommended for teams > 2 agents)

For complex orchestrations requiring inter-agent communication, prefer native Agent Teams:

Recommendation: Use Task sub-agents (this skill) for focused and independent tasks. Use Agent Teams (/work:work-team) for teams of 3+ agents requiring discussion and coordination.

See the agent-teams skill for full documentation.

Rules

• ALWAYS verify dependencies between sub-tasks
• NEVER parallelize modifications on the same files
• ALWAYS establish the map of modified files BEFORE launching agents
• ALWAYS provide full context to each agent
• COMBINE results into a coherent report
• PREFER isolation: "worktree" when agents modify many files

Dispatched sessions (CLI 2.1.142+)

For workloads that outgrow in-process Task sub-agents, the claude agents CLI dispatches background sessions with their own configuration. Flags --add-dir, --settings, --mcp-config, --plugin-dir, --permission-mode, --model, --effort let each dispatched session run with a tailored model/effort/permission profile. Pair with the agent-teams skill for coordinated multi-process work, and use Agent View to monitor running sessions.

Since CLI 2.1.198 (July 2026), in-process Task sub-agents also run in the background by default — the lead keeps working while they run and is notified when each finishes, so a fan-out no longer blocks the main turn. Dispatched sessions that finish code work in a worktree now commit, push, and open a draft PR on their own, and fire the Notification hook (agent_needs_input / agent_completed) instead of stopping to ask — design the merge step around reviewing those drafts.