What Is a Workflow? Claude Code's Multi-Agent Orchestration, Explained

If you’ve watched Claude Code work on a big task in 2026, you may have seen it announce something like “launching a workflow with 12 agents” — and then a /workflows command that shows live progress as dozens of subagents fan out, verify each other, and converge on an answer. New users ask the same two questions every time: what is a workflow, and what does “orchestration” actually mean?

This article answers both, from zero. No prior multi-agent knowledge required.

The Short Answer

A Workflow is a small JavaScript program that Claude Code writes and the harness executes. The script’s job is coordination: it spawns subagents, routes their outputs into each other, runs things in parallel, and decides what happens next — using ordinary loops and conditionals instead of model improvisation.

Orchestration is exactly what it sounds like: one score, many musicians.

The score is the workflow script. It makes the orchestration readable and rerunnable: which agents run, in what order, and on which inputs. The agents’ model outputs are still non-deterministic.
The musicians are the subagents. Each one is a full Claude agent with its own context window and tools. They exercise judgment — reading code, weighing evidence, writing analysis — inside the part the score assigns them.

The division of labor is the whole idea, and it’s worth memorizing:

Control flow lives in code. Judgment lives in models.

A model deciding “should I spawn another reviewer?” mid-task is improvisation — flexible, but unrepeatable and hard to budget. A script deciding it — for loop, if statement — is orchestration.

From One Agent to an Orchestra

Workflows didn’t appear out of nowhere. They’re the fourth step in an evolution you can trace through Claude Code’s history:

Stage 1: Solo agent
  ┌─────────┐
  │ Claude  │  one context window does everything:
  └─────────┘  read, plan, edit, test

Stage 2: Subagent fan-out (Agent tool)
  ┌─────────┐
  │ Claude  │──→ agent: "search the codebase"
  │ (main)  │──→ agent: "read these 40 files"
  └─────────┘    results return to the parent only

Stage 3: Agent teams
  ┌─────────┐    ┌─────────┐
  │ agent A │←──→│ agent B │  named agents that persist,
  └─────────┘    └─────────┘  continued via SendMessage

Stage 4: Scripted workflows
  ┌────────────────────────────┐
  │  JavaScript orchestration  │
  │  loops · phases · fan-out  │
  └──┬──────┬──────┬──────┬────┘
   agent  agent  agent  agent   (repeatable score,
                                 judging musicians)

Stage 1 is where everyone starts: one agent, one context window. It works until the task outgrows what a single context can hold.

Stage 2 added the Agent tool: the main agent delegates multi-file reading and searching to subagents and keeps only conclusions — not file dumps — in its own context. Subagents run in the background by default, and their final message returns to the caller only. (Covered in depth in Session 4: Subagents & Context Isolation.)

Stage 3 made agents durable collaborators: a subagent can be given a name, and the parent can continue it later — context intact — via SendMessage, mailbox-style, instead of starting fresh. (See Session 9: Agent Teams & Communication.)

Stage 4 — the Fable 5-era Workflow tool — changed who decides the structure. In stages 2 and 3, the main agent improvises delegation turn by turn. In a workflow, the structure is written down as code and can be inspected and rerun. The runtime executes the script in the background; /workflows shows live progress the whole time.

Why a Script? Why Repeatability Matters

Moving coordination into code does not make model answers deterministic. It makes the plan inspectable and rerunnable, which is the useful boundary.

1. Repeatable structure. The same saved script preserves its phases, loops, branching, and fan-out shape. Agent responses can still vary, so each run still needs verification.

2. Resumable runs. You can pause and resume a run in the same Claude Code session. Completed agents reuse their saved results; an agent that was still running starts again. Exiting Claude Code starts the workflow fresh next session.

3. Parallelism with runtime limits. The runtime allows up to 16 concurrent agents and 1,000 agents total per run. Those caps prevent runaway fan-out; they are not a claim that every large workflow is cheap or safe.

4. Observable cost, not a hard token budget. /workflows shows per-agent token use and lets you stop a run. Claude Code can warn when a run schedules more than 25 agents or projects more than 1.5 million tokens, and /config offers a size guideline. Both are advisory; the official runtime does not document a +500k hard ceiling or a script-level budget API.

A Gentle Tour: agent(), parallel(), pipeline()

You don’t need the full API to get the concept (that deep dive is Session 27: The Workflow Tool). Three primitives carry most workflows:

agent(prompt, opts?) — spawn a subagent and get back its final text. Pass a JSON Schema via opts.schema and you get a validated object instead — the subagent is forced through a structured-output tool, with automatic retry if the shape doesn’t match. Per-agent model and effort options let you put cheap models on mechanical work and top-tier models on judgment.
parallel(thunks) — run several things at once and wait for all of them (a barrier). A thunk that throws resolves to null rather than crashing the run, so you filter with .filter(Boolean).
pipeline(items, stage1, stage2, ...) — each item flows through every stage independently, with no barrier between stages: item A can be in stage 3 while item B is still in stage 1. Total wall-clock time is just the slowest single item’s chain.

Here is a complete, simple workflow — review a list of changed files in parallel, then merge the findings:

export const meta = {
  name: 'review-changes',
  description: 'Review changed files in parallel, then merge findings',
  phases: [{ title: 'Review' }, { title: 'Merge' }],
};

phase('Review');
const files = args.files; // passed in when the workflow is invoked

// Fan out: one reviewer per file, all running concurrently.
const reports = (await parallel(
  files.map((file) => () =>
    agent(`Read ${file} and report any correctness bugs you find.`, {
      label: `review ${file}`,
      phase: 'Review',
      model: 'haiku',   // cheap tier for mechanical per-file reading
      effort: 'low',
    })
  )
)).filter(Boolean); // a failed reviewer becomes null — drop it

phase('Merge');
log(`Collected ${reports.length} per-file reports.`);

// One high-effort agent merges and ranks everything.
await agent(
  `Merge these review reports. Deduplicate and rank by severity:\n\n` +
  reports.join('\n---\n'),
  { phase: 'Merge', effort: 'high' }
);

A few things to notice:

The script starts with export const meta = ... — a pure literal (no variables, no calls) declaring the name, description, and phases. Each phase() call matches a title declared there, which is what powers the live progress view.
args is how the workflow gets parameterized input; log() writes narrator lines for you to read as it runs.
The script itself has no filesystem access and no Node.js APIs — agents have tools; the score does not touch instruments.
The merge step uses parallel’s barrier deliberately: it needs every report before deduplicating across them. That’s the rule of thumb — a barrier is justified only when the next stage needs cross-item context from all of the previous one. Per-item chains that don’t compare across items belong in pipeline, where nothing waits.

Workflows you want to keep live in .claude/workflows/ and can be invoked by name later; one workflow can even call another with workflow(), one nesting level deep.

Beyond Fan-Out: Quality Patterns

Fan-out is table stakes. The interesting part of orchestration is using structure to make answers more likely to be true:

Adversarial verify — for each finding, spawn independent skeptic agents explicitly prompted to refute it; if a majority succeed, the finding dies. This filters plausible-but-wrong results before they reach you.
Judge panel — several independent attempts at the same problem from different angles, scored by parallel judges, with the final answer synthesized from the winner plus the best ideas of the runners-up.
Loop-until-dry — for “find all the X” tasks of unknown size, keep spawning finders until several consecutive rounds turn up nothing new.

These deserve their own session — Session 28: Orchestration Quality Patterns walks through each with code. The takeaway for now: answer quality becomes a structural property of how you orchestrate, not just a property of the model.

Solo, Subagent, or Workflow?

More machinery is not always better. Here’s the honest decision table:

Situation	Reach for	Why
Single-fact lookup, you know the file	Solo (no delegation)	Delegation overhead isn’t worth it — just read it
Multi-file reading, searching, exploration	Subagent (Agent tool)	Keeps conclusions, not file dumps, in the main context
A collaborator that must remember prior work	Named agent + SendMessage	Continue it with context intact instead of restarting
Multi-stage process over many items, needing verification or resume	Workflow	Repeatable control flow, parallelism, progress inspection, same-session resume

How to Opt In

Workflows are opt-in — a single workflow can spawn dozens of agents and consume serious token volume, so the harness requires you to explicitly ask for that scale. Without opt-in, Claude Code uses individual subagents or works solo. Three ways in:

Say it: include “use a workflow” in your prompt for a one-off.
Ultracode: include the keyword “ultracode” in a prompt, or enable it session-wide via /effort. Ultracode = xhigh reasoning effort + standing multi-agent workflow orchestration on every substantive task. (Full guide: Ultracode & Effort Levels.)
Via a skill: a skill’s instructions can direct Claude Code to orchestrate with a workflow for its task.

Before a large run, test a small slice, inspect projected scale, and watch token use in /workflows. A size guideline helps shape the script, but it is not a spending cap.

Key Takeaway

A workflow is a score, not a soloist. Claude Code writes JavaScript to decide what runs, when, and in what order — and delegates every act of judgment to subagents. You get an inspectable, rerunnable control flow with parallelism and progress visibility, while keeping the important truth explicit: model outputs still vary and must be verified.

Next time a task feels too big for one context window, don’t ask for a bigger agent. Ask for an orchestra.