Choosing an Orchestration Pattern

The previous lesson covered the single delegate: spawn one subagent, it works in an isolated context, it hands back a summary. That is the floor. This lesson is the map of everything above it — the four distinct ways Claude Code coordinates many agents at once.

Learners conflate these constantly, so start with the mental model and hold it firmly: the paradigms differ along one axis — how the agents communicate and where their intermediate work lives. Get that axis right and every other property (scale, cost, status) falls out of it.

                     COORDINATING MANY AGENTS

  Subagents        Dynamic workflows     Agent teams      Background /
  (in-session)     (scripted fan-out)    (peer sessions)  agent view
  ───────────      ──────────────────    ─────────────    ───────────
  results to       results in script     mailbox +        human
  main context     variables             shared tasks     supervises
  a few            up to 1,000 / 16      3-5 sessions     a handful
  GA               research preview      EXPERIMENTAL     research preview

The single most useful sentence in this module: a subagent lives inside one session and reports a summary up; the three paradigms above it run as their own thing — a separate script runtime, separate peer sessions, or separate background sessions. That separation is exactly why each scales, costs, and communicates differently.

Here is the spine of the module — the one table to internalize. Read it down the Communication model column first; that is the axis everything else hangs on.

Notice how communication predicts everything:

• Subagents don't talk to each other at all — they answer up to the parent. So they stay cheap (the parent only pays for summaries) but they can't divide a fuzzy problem among themselves.
• Workflows also have no peer messaging; the script glues outputs together by string concatenation. That makes them deterministic and scriptable — and lets them go to 1,000 agents because the chatter never hits your context window.
• Agent teams are the only paradigm with a real message bus (a mailbox) plus a shared task list. That is what lets peers self-coordinate — and it is why each one needs a full context window, making them the most expensive per agent.
• Background agents don't coordinate with each other either; you are the coordinator, checking in via the agent view.

Four paradigms, one rule. Match the shape of the work to the paradigm:

The failure mode is reaching for the heavyweight tool by default. Most tasks are a subagent or a workflow. Agent teams are powerful but the most expensive and most experimental — save them for problems that genuinely require peers talking to each other. If you can express the work as "do the same thing to many items and combine the results," it is a workflow, not a team.

A worked classification:

Task: "Find every SQL query in the repo that lacks parameterization,
       verify each finding, and give me one report."
→ Deterministic, large-scale, no peer discussion needed.
→ WORKFLOW (fan-out finders, separate verifiers, concatenate survivors).

Task: "Three of us — a backend, a frontend, and a test writer — build
       this feature together, handing work back and forth."
→ Fuzzy, agents must coordinate and hand off.
→ AGENT TEAM (mailbox + shared task list).

Task: "Keep an eye on CI and fix the flaky test while I'm at lunch."
→ Run while away, human checks back.
→ BACKGROUND AGENT (claude --bg ...), monitored via `claude agents`.

Task: "Map everywhere we call the payments API so I can plan a change."
→ One heavy, self-contained read.
→ SUBAGENT.

A dynamic workflow is Claude Code's large-scale orchestrator (research preview, requires v2.1.154+ — check claude --version). You describe a task in natural language; Claude writes a JavaScript script, and a separate runtime executes it, coordinating tens to hundreds of subagents. Hard caps: 1,000 agent calls per run and 16 concurrent (bounded by CPU cores).

The defining behavioral difference from plain subagents: orchestration logic lives in a script, so intermediate results stay in script variables — outside your context window. Only the final, verified answer lands in your session. You don't pay context for every agent's chatter. That is the cost/quality lever.

Three ways to trigger one:

1. Put the keyword ultracode anywhere in a prompt (natural language like "use a workflow" also works).
2. Run a saved workflow command — a /<name> you saved earlier from a previous run.
3. Set /effort ultracode so Claude auto-deploys a workflow when a task warrants it (combines xhigh reasoning + workflow planning; session-only — reset with /effort high).

There's a built-in one worth knowing: /deep-research <question> fans web searches across angles, cross-checks sources, votes on claims adversarially, and returns a cited report with unverified claims filtered out.

The scripting primitives are conceptual — spawn one agent (returns a string), run a batch in parallel (a barrier: all must finish), stream items through a pipeline (no per-stage barrier), and phase/log for the progress display. Data flow between agents is pure string concatenation / JSON — there is no message bus and agents never talk to each other; the script parses and stitches outputs.

Monitor and manage runs with /workflows: arrow keys to select, Enter to drill into a phase (agent count, tokens, elapsed), p pause/resume, x stop, r restart an agent, s to save the run's script as a reusable /<name> command (in .claude/workflows/ for the project or ~/.claude/workflows/ for you). Pause/resume returns cached results for finished agents — but only within the same session; exiting Claude Code restarts the workflow fresh next time.

An agent team is the only paradigm where agents are full peer sessions that message each other. It is experimental and disabled by default (requires v2.1.32+). Enable it explicitly:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
# or in settings.json:
# { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

Your main session becomes the lead; it spawns independent teammate sessions, each with its own full, fresh context window. They self-coordinate through two shared structures:

• A shared mailbox for inter-agent messaging (the message bus that no other paradigm has).
• A shared task list at ~/.claude/tasks/{team-name}/ — states pending → in-progress → completed, dependencies tracked automatically, file locking to prevent races.

You drive a team in natural language to the lead: "Create an agent team to build this feature. Spawn a backend teammate, a frontend teammate, and a test-writer teammate." You can spawn a teammate from a subagent definition by name (its system prompt, tools allowlist, and model carry over) — but note its skills and mcpServers frontmatter are NOT applied; teammates load skills/MCP from project/user settings. Talk to a teammate with Shift+Down (in-process) or by clicking its pane (tmux/iTerm2 split). Quality-gate hooks are team-specific: TaskCompleted (exit 2 blocks a 'done' that fails your bar), TaskCreated, and TeammateIdle (exit 2 keeps an idle teammate working).

Because each teammate is a full context window, cost scales linearly with the number of teammates — this is the most expensive per agent of all four paradigms. Size to 3-5 teammates, ~5-6 tasks each, and don't leave a team running unattended.

The fourth paradigm is about time, not coordination: independent sessions that run unattended while you do something else, with a human supervising asynchronously. There is no peer messaging — you are the coordinator.

Agent view (research preview, v2.1.139+) is the control room. Open it with claude agents — a unified screen grouped by state (Needs input / Working / Completed) with live counts. Navigate with ↑/↓, Space to peek, Enter to attach, Ctrl+T to pin (pinned sessions survive; unpinned idle ones stop after ~1 hour), Ctrl+X to delete. Dispatch a background session with claude --bg "<prompt>" (optional --name, --agent, --model, --permission-mode); manage shells with claude attach <id>, claude logs <id>, claude stop <id>, claude rm <id>. Background sessions isolate into git worktrees under .claude/worktrees/ before their first edit, so they don't disturb your working tree.

For scheduling there are lighter tools (touched in detail elsewhere in the module):

• /loop [interval] [prompt] — session-scoped recurring task (e.g. /loop 30m run the tests); omit the interval to let Claude self-pace; 7-day expiry, max 50 concurrent.
• /goal <condition> — Claude pursues a goal across turns until a small fast model judges the condition met from the transcript (so the condition must be provable from Claude's own output).
• /schedule (routines) — durable cloud schedules on Anthropic infrastructure, minimum 1-hour interval, with schedule/API/GitHub triggers; these run autonomously with no permission prompts.

Monitoring helpers: the Monitor tool streams a background process's output into the conversation so Claude reacts without a polling loop; PushNotification pings your desktop/phone at a milestone; /tasks lists and stops background streams.

Two cross-cutting facts thread through every choice: what it costs and whether it's even stable yet.

Cost mental model. Cost scales roughly linearly with active agents, but where the tokens go differs by paradigm:

• Subagents preserve context — they summarize back, so the parent pays for summaries, not raw exploration. Cheapest.
• Workflows hold intermediate state in script variables, outside your context window. Per-agent context is cheap, but they can spawn hundreds, so the total can be large. Test on a small slice first — one directory, a narrow question — then scale, watching per-phase tokens in /workflows.
• Agent teams give each teammate a full context window — the most expensive per agent. Keep teams small (3-5) and don't leave them running.
• Background agents each hold a full session too; cost accrues for as long as they run, which is why idle ones auto-stop after ~1 hour.

Track spend with /usage (per skill/subagent/plugin/MCP) and /insights (history and trends). The universal rule: prove the pattern on a small slice before you fan out wide.

Status & availability — say it plainly to yourself before you rely on a feature.

Note that ultracode and ultrathink are current keywords, not deprecated: ultracode triggers a workflow / xhigh effort, and ultrathink requests deeper reasoning for one prompt.