Dynamic Workflows: Scripted Fan-Out

The single-subagent lesson covered delegating ONE heavy task to a helper that reports a summary back. This lesson is about coordinating many agents — and dynamic workflows are the flagship feature for it.

With subagents, skills, and agent teams, Claude is the orchestrator: turn by turn, it decides what to spawn next, and every result it gets back lands in a context window. That works for a handful of agents. It does not scale to hundreds — you'd drown the context window in intermediate chatter long before you reached the answer.

A dynamic workflow moves the plan out of the conversation and into code. Claude WRITES a JavaScript orchestration script for the task you describe, and a separate runtime executes that script in the background. The loop, the branching, and — critically — the intermediate results all live inside the script. Your session's context holds only the final answer.

WITHOUT a workflow (Claude orchestrates, turn by turn)
  every agent's result  ──►  Claude's context window  (fills up fast)

WITH a workflow (the SCRIPT orchestrates)
  agent 1 result ─┐
  agent 2 result ─┤──►  SCRIPT VARIABLES  ──►  final answer ──► your session
  ... agent 348 ─┘     (outside the context window)

That single shift — intermediate state in script variables, not the context window — is the whole point. It is what lets one prompt fan out to hundreds of subagents and still return a clean, single result. Two consequences follow: the orchestration is now a script you can read, save, and rerun, and it can apply a repeatable quality pattern (e.g. have independent agents adversarially review each other's findings before any are reported) rather than just running more agents.

Learners conflate Claude Code's multi-agent modes constantly. The honest way to tell them apart is to ask who holds the plan and where intermediate results live.

The decisive rows are the last three. Workflows are the only paradigm where the plan lives in code and intermediate results stay out of the context window — which is exactly why they're the one that scales to hundreds of agents.

Decision rule of thumb:

• Need deterministic, repeatable, large-scale fan-out (audit 500 files, cross-checked research, a big migration)? → workflow.
• Need agents to talk to each other and divide a fuzzy problem (debate, parallel feature work with handoffs)? → agent team (a different feature, experimental).
• Just need context isolation for one heavy read? → a subagent (the previous lesson).

There are three trigger paths. The first is the quickest; the third hands the decision to Claude.

1. The ultracode keyword in a prompt. Include ultracode anywhere in a prompt and Claude writes a workflow for that one task instead of working through it turn by turn. Saying it in plain language ("use a workflow", "run a workflow") works too — Claude treats a direct request as the same opt-in.

ultracode: audit every API endpoint under src/routes/ for missing auth checks

Claude Code highlights the keyword in your input. If you didn't mean to start a workflow, press Option+W (macOS) or Alt+W (Windows/Linux) to dismiss the highlight for that prompt. To stop the keyword triggering at all, turn off Ultracode keyword trigger in /config.

2. A saved /<name> command. Once a run does what you wanted, you can save its script (see the monitoring section). It then runs as /<name> in future sessions — a reusable orchestration primitive.

3. /effort ultracode (auto-decide). Ultracode is a Claude Code setting that combines xhigh reasoning effort with automatic workflow orchestration. With it on, Claude decides on its own when a substantive task warrants a workflow and deploys one — a single request can even spawn several workflows in a row (understand the code, make the change, verify it). It lasts the session and resets on a new one; drop back with /effort high for routine work.

/effort ultracode

The bundled workflow: /deep-research. The fastest way to see a workflow in action is the one Claude Code ships with. /deep-research <question> fans out web searches across several angles, fetches and cross-checks the sources, votes on each claim, and returns a cited report with claims that didn't survive cross-checking already filtered out. (It requires the WebSearch tool to be available.)

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

Claude writes the script; you read it, you don't write it from scratch. That framing matters because the exact API surface names differ by version and by source. The official workflows.md describes dispatching subagents with spawn(definition, prompt, args); third-party writeups describe higher-level helpers agent(), parallel(), pipeline(), phase(), log(). Rather than memorize names that drift, learn the concepts and then read the script Claude generates for your version.

The conceptual primitives:

The single most important fact: an agent call returns a STRING. There is no shared memory and no agent-to-agent channel. The script feeds one agent's string output into the next agent's prompt, and if structured output is needed, the script parses it — the agents do not talk to each other.

The official docs note you can ask for the script's path (every run writes its script under your session's directory in ~/.claude/projects/), open it to read the orchestration Claude wrote, diff it against a previous run, or even edit it and ask Claude to relaunch from the edited version.

Every workflow script carries a literal export const meta block. "Literal" is the whole rule: no function calls, no variables, no dynamic construction, no parsing tricks — any deviation breaks parsing. It must be a plain object the runtime can read statically.

export const meta = {
  name: 'audit-auth',
  description: 'Audit every route for missing auth checks',
  phases: [{ title: 'Scan routes' }, { title: 'Cross-check findings' }], // optional
  inputSchema: { /* JSON Schema */ }                                       // optional
};

• name and description are required; phases and inputSchema are optional.
• A saved workflow can accept input through an args parameter — the script reads it as a global named args. If you call the saved command with structured data ("run /triage-issues on issues 1024, 1025, 1030"), the script can call array/object methods on args directly; if args is omitted, the global is undefined.

Data flow is string concatenation / JSON serialization — nothing more. There is no message bus, no shared state, no agent-to-agent communication. Each agent receives a prompt string and returns a string; the SCRIPT concatenates outputs into the next input and parses anything it needs. This is deliberately the opposite of agent teams (which DO have a shared mailbox and task list). In a workflow, the script is the only coordinator.

The runtime executes the script in an isolated environment, separate from your conversation, and enforces hard limits. Teach these as guardrails:

Two permission facts worth flagging. First, the subagents a workflow spawns always run in acceptEdits mode and inherit your tool allowlist, regardless of your session's permission mode — file edits are auto-approved. Second, shell commands, web fetches, and MCP tools that aren't on your allowlist can still prompt you mid-run; to avoid interruptions on a long run, add the commands the agents need to your allowlist before starting.

Workflows run in the background, so your session stays responsive while agents work. /workflows lists running and completed runs; select one and press Enter to open its progress view, which shows each phase with its agent counts, token totals, and elapsed time. Drill into a phase, then an agent, to read its prompt, recent tool calls, and result.

Resume is cheap: completed agents return their cached results and only the remaining agents run live. But resume works only within the same Claude Code session — exit Claude Code and the next session starts the workflow fresh (there's no cross-session checkpoint).

Save for reuse: from /workflows, press s, then Tab toggles the save location — .claude/workflows/ (project, shared via git) or ~/.claude/workflows/ (personal). Saved workflows appear as /<name> commands and accept input via the args parameter, so they become reusable orchestration primitives (usable in CI via claude -p and the Agent SDK). If a project and a personal workflow share a name, the project one wins.

Cost discipline. A run spawns many agents, so it can use meaningfully more tokens than the same task in conversation, and it counts toward your plan's usage and rate limits. Test on a small slice first — one directory, a narrow question — watch per-phase tokens in /workflows, and stop at any time without losing completed work.

Disabling. Turn workflows off three ways, all of which remove /deep-research, the ultracode keyword trigger, and ultracode from the /effort menu:

• Toggle Dynamic workflows off in /config.
• Set "disableWorkflows": true in ~/.claude/settings.json (or managed settings, org-wide).
• Set CLAUDE_CODE_DISABLE_WORKFLOWS=1.