The Workflow Tool: Scripted Multi-Agent Orchestration

What You’ll Learn

A dynamic workflow is a JavaScript script that coordinates subagents while a dedicated runtime handles the control flow in the background. Use it when the loop, branching, or fan-out should be readable and repeatable instead of living only in the model’s conversation context.

By the end, you’ll know:

• When to use a workflow instead of a subagent, skill, or agent team
• How to launch, inspect, approve, save, and rerun a workflow
• The documented shape of meta, agent(), pipeline(), parallel(), phase(), and args
• The runtime’s real limits and same-session resume boundary
• Which failure and budget assumptions should stay out of your scripts

Choose the Right Coordination Layer

Mechanism	Who holds the next step?	Best fit
Subagent	Claude, turn by turn	A few delegated tasks whose results return to one context
Skill	Claude following stored instructions	A reusable method or domain procedure
Agent team	A lead supervising long-running peers	Teammates that share tasks and message one another
Workflow	The script runtime	Large, repeatable loops, fan-out, branching, and cross-checking

Workflows are not automatically better. For a single lookup or a tightly coupled edit, one agent has less overhead. Reach for a workflow when code is genuinely better at the bookkeeping.

Dynamic workflows require Claude Code 2.1.154 or later. They are available on paid plans and supported API/cloud-provider surfaces; Pro users enable them in the Dynamic workflows row of /config.

Three Ways to Run One

Start with the bundled workflow

/deep-research What changed in the Node.js permission model between v20 and v22?

/deep-research fans out research, cross-checks claims, and returns one cited report.

Ask for a workflow

use a workflow to audit every route handler under src/routes/ for missing authentication checks, then adversarially verify each finding

The ultracode keyword is another explicit one-task trigger. It does not change the session’s saved effort level.

Let ultracode decide

/effort ultracode

This session setting combines xhigh effort with automatic workflow planning for substantive tasks. See Session 26 for its availability and scope.

What the Saved Script Looks Like

Claude normally writes the script for you. A small saved workflow has this documented shape:

export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: {
    type: 'object',
    required: ['files'],
    properties: {
      files: { type: 'array', items: { type: 'string' } },
    },
  },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)

The script starts with a literal meta export and uses plain JavaScript with top-level await.

• agent() starts one subagent.
• pipeline() applies stages across a list of items.
• parallel() runs independent functions concurrently and waits for the group.
• phase() groups work in the progress view when meta.phases is present.
• args contains structured input passed to a saved workflow; it is undefined when omitted.

The Agent SDK reference is the source of truth for exact input and output types. Do not invent a return, exception, or in-script budget contract based on an example.

Approval and Permissions

Before an interactive run, Claude Code can show the planned phases and let you:

• run once;
• always allow that workflow in this project;
• inspect the raw script; or
• cancel.

The exact prompt depends on permission mode. Workflow agents run in acceptEdits mode and inherit the session’s tool allowlist. Shell, web, and MCP calls outside that allowlist can still ask for permission during the run. A workflow cannot stop mid-run to ask an ordinary business question; split human sign-off points into separate workflows.

Watch, Pause, and Save

Run /workflows to inspect active and completed runs. The view shows phases, agents, elapsed time, and token usage. From there you can pause, resume, stop, restart an agent, or save the script.

Saved locations become slash commands:

• .claude/workflows/ for a project workflow shared through the repository
• ~/.claude/workflows/ for a personal workflow available across projects

A saved script reads invocation input from args, so one orchestration can work on different paths, issues, or research questions without editing its source.

Runtime Boundaries

The documented constraints are intentionally concrete:

Boundary	Current behavior
Script access	No direct filesystem or shell access; agents use tools
Mid-run input	No ordinary user input; only agent permission prompts can pause
Concurrency	Up to 16 agents, fewer on limited CPUs
Total workers	1,000 agents per run
Session exit	A later session starts the workflow fresh

Pause and resume work only within the same Claude Code session. Completed agent() calls can return cached results; an agent that was still running when paused starts again. A smaller-grained fan-out therefore preserves more useful progress than one very long worker.

Cost and Scale

Workflows can consume substantially more tokens than a single conversation. Before a large run:

1. rehearse on one directory or a small sample;
2. watch token use in /workflows;
3. stop the run if its evidence is no longer improving; and
4. set a workflow size guideline in /config if you want Claude to aim smaller.

The size setting is advice to Claude, not enforcement. From 2.1.203, runs above 25 scheduled agents or 1.5 million projected tokens receive a Large workflow warning. That warning is also advisory and is suppressed when ultracode is on because the session already opted into large runs.

Practical Design Rules

• Fan out only work that is truly independent.
• Put cross-item deduplication or ranking after the relevant results exist.
• Ask agents for compact, structured evidence rather than full transcripts.
• State a stop condition in the task: a passing check, two dry rounds, or no further progress.
• Log sampling, skipped work, and unresolved claims in the final report.
• Use separate stages when a human decision is required between them.

Key Insight

A workflow moves coordination state out of the conversation and into code. The model still supplies judgment inside each agent, but loops, fan-out, and intermediate values become inspectable and reusable. That makes orchestration easier to audit without pretending every internal behavior is a guaranteed API contract.

Next Session

Session 28 turns these mechanics into orchestration quality patterns: independent search, adversarial verification, explicit stopping, and auditable evidence.

Official Sources

• Dynamic workflows
• Choosing among agent mechanisms
• Agent SDK Workflow tool types