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 is deterministic — the same script does the same thing every time. It decides who plays when: which agents run, in what order, on which inputs.
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   (deterministic 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 once, as code, and then executed exactly. The harness runs the script in the background, returns a task ID, and notifies you on completion; /workflows shows live progress the whole time.

Why a Script? Why Determinism Matters

Making the coordination layer deterministic sounds like a technicality. It’s actually where most of the value comes from.

1. Reproducibility. The script bans nondeterminism outright: Date.now(), Math.random(), and argumentless new Date() all throw inside a workflow script. Same script, same behavior. There is no “it worked last time” — the score doesn’t change between performances.

2. Resume from cache. Every workflow run persists its script, and a journal.jsonl records what each agent actually returned. Relaunch with resumeFromRunId and the harness replays the longest unchanged prefix of agent() calls straight from cache — only edited or new calls run live. Fix a prompt in stage 3 of a 50-agent run and you re-pay for stage 3, not stages 1 and 2. This only works because the control flow is deterministic; that’s why the nondeterministic built-ins are banned.

3. Parallelism without chaos. Fan-out in code is safe fan-out. A workflow runs up to min(16, CPU cores − 2) agents concurrently, queues the excess, caps a run at 1,000 agents total as a runaway-loop backstop, and errors explicitly (never silently truncates) if you pass more than 4,096 items to a single fan-out call.

4. Budget enforcement. Write “+500k” in your prompt and the turn gets a token target, surfaced inside the script as a budget object: budget.total, budget.spent(), budget.remaining(). The pool is shared across the main loop and every workflow in the turn — and it’s a hard ceiling: once spent reaches total, further agent() calls throw. A script can check budget.remaining() and wind down gracefully; an improvising model has no equivalent brake.

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	Deterministic control flow, parallelism, budgets, resume-from-cache

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.

Add a token directive like “+500k” when you opt in, and the whole orchestra plays inside a hard budget.

Key Takeaway

A workflow is a score, not a soloist. Claude Code writes deterministic JavaScript to decide what runs, when, and in what order — and delegates every act of judgment to subagents that are good at judging. You get the reliability of code (reproducibility, resume, parallelism, budgets) multiplied by the intelligence of models, instead of having to choose between them.

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