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

Task	Parallel agents	Result
Full audit	qa-security + qa-perf + wcag-audit	Combined report
Code review	native /code-review (or qa-claudemd per convention scope)	Issue list
Exploration	work-explore per functional domain	Code map

Development

Task	Parallel agents	Result
Tests per module	dev-tdd per service	Test suite
Documentation	doc-generate per component	Complete docs
Migration	ops-deps audit + one dev-tdd per dependency	Complete migration

Business

Task	Parallel agents	Result
Market research	biz-competitor + biz-personas	Complete analysis
Launch	growth-landing + growth-seo + growth-analytics	Launch kit

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

Situation	Action
2 agents modify the same file	SEQUENTIAL mandatory
2 agents modify the same folder	Check the specific files
Read-only agents (audit)	PARALLEL always OK
Shared config (package.json, tsconfig)	SEQUENTIAL for edits

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:

	Sub-Agents (Task)	Agent Teams
Communication	Return to parent only	Direct messaging between agents
Coordination	Main agent handles everything	Shared task list
Token cost	Low	High (1 context per agent)
Ideal for	Focused tasks, combined results	Complex collaboration, debate, consensus

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.