Library
Claude Code Documentation (June 2026) · 11 of 15
Claude Code Documentation (June 2026)
ai CRITICAL

Parallel Orchestration — Decision Guide

Claude Code Documentation (June 2026) Anthropic
subagents agent-view agent-teams dynamic-workflows parallelism

Key Principle

When work is too big for one context, scale it out — but every surface multiplies token cost and adds coordination overhead, so pick by three questions (p. Chunk 008):

  1. Who holds the plan / coordinates?
  2. Do the workers need to talk to each other?
  3. Do the tasks touch the same files?

The ladder (lowest cost → highest): subagents → agent view → agent teams → dynamic workflows. In every approach the workers are Claude sessions; to involve a different tool, expose it to Claude as an MCP server (p. Chunk 007).

Why This Matters

The wrong choice means either lost work (no isolation → merge conflicts) or wasted tokens (over-coordinating independent tasks) (p. Chunk 008). Agent teams in particular spend the most context — each teammate is a full, separate Claude instance with its own window — so "don't default to teams"; the extra parallelism is wasted and expensive if roles don't actually need to interact (p. Chunk 003).

Good Examples

  • Subagents — delegated workers inside one session that do a side task in their own context and return only a summary. Coordinator: Claude, turn-by-turn. Workers talk: no (report to the spawning conversation only). Token cost: lowest. Use when "a side task would flood your main conversation with search results, logs, or file contents you won't reference again" (p. Chunk 007). Example: "Use subagents to investigate how our authentication system handles token refresh."
  • Agent view — one screen (claude agents) to dispatch and monitor independent background sessions, each its own process. Coordinator: you, check back later. Workers talk: no (report to you). Use when you have several independent tasks to hand off and "step in only when one needs you." Each dispatched session gets its own git worktree automatically (research preview) (p. Chunk 007).
  • Agent teams — multiple coordinated sessions with a shared task list and inter-agent messaging, managed by a lead (experimental, disabled by default; enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). Coordinator: Claude (the lead) plans, assigns, supervises. Workers talk: yes (shared task list + mailbox). Use "when you want Claude to split a project into pieces, assign them, and keep the workers in sync" — only when cross-talk is actually needed (p. Chunk 007, 003).
  • Dynamic workflows — a script runs many subagents and cross-checks their results. Coordinator: a script, not Claude's turn-by-turn judgment. Use for "work too big to coordinate one turn at a time or that needs more than a single pass: codebase-wide audit, 500-file migration, cross-checked research, plan from several angles" (p. Chunk 007, 008).

Counterpoints

  • File overlap = use worktrees. Subagents and self-run sessions can each take a separate worktree. Agent teams do NOT isolate teammates in worktrees — partition the work so each teammate owns a distinct file set, or teammates clobber each other (p. Chunk 008).
  • /agents ≠ claude agents. /agents opens a panel (Running tab = live subagents in the current session; Library tab = create/edit subagents). claude agents opens agent view for background sessions — separate surfaces despite the similar name (p. Chunk 008, 007).
  • Don't confuse adjacent surfaces. /batch is a packaged use of subagents + worktrees (splits one big change into 5–30 worktree-isolated subagents, each opening a PR), not a new coordination style. A forked subagent inherits your full context instead of starting fresh — a way to spawn a subagent, not a separate surface. A background bash command spawns no agent. A Routine runs on a schedule in Anthropic's cloud, not in parallel on your machine (p. Chunk 008).
  • Parallelism multiplies quota and cost. Background sessions consume subscription quota exactly like interactive ones — 10 in parallel ≈ 10× quota (p. Chunk 007).

Key Commands & Config

# CHECK ON RUNNING WORK (per surface)
claude agents     Agent view: every background session, its state, which need input
/agents           Panel — Running tab (live subagents) + Library tab (manage subagents)
/tasks            Anything backgrounded in the current session: check, attach, or stop
/workflows        Dynamic-workflow runs: each run's phase + how many agents finished
/batch            Split one big change into 5–30 worktree-isolated subagents (each a PR)

# ENABLE / SPAWN
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1     Enable agent teams (off by default)
teammateMode  /  --teammate-mode <value>  in-process (default, v2.1.179+) | auto | tmux
"Spawn three teammates ... one on UX, one on architecture, one devil's advocate"
"Require plan approval before they make any changes."   (gates risky teammate work)

Rules of Thumb

  • Match the surface to who holds the plan, whether workers talk, and whether files overlap.
  • Subagents for quick workers that report back; teams only when teammates must share findings and coordinate.
  • Isolate overlapping work in worktrees — and remember teams don't do this automatically; partition files yourself.
  • Reach for dynamic workflows only when the job outgrows a handful of subagents or needs cross-checked verification.

Related References

Diagram

Diagram