Claude Code workflows: run many subagents from a script

A Claude Code workflow, or dynamic workflow, is a JavaScript script Claude writes that runs many subagents for you: one per file, per source or per angle on a problem, 16 at a time by default and up to 1,000 in a run. The runtime executes the script in the background while your session stays free, and Claude's context receives only the final answer, not every agent's transcript.

Workflows are on every paid plan, with Anthropic API access, and on Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry; on Pro you turn them on in /config. They are meant for jobs too big for one conversation: a bug sweep across a codebase, a 500-file migration, research whose sources must be checked against each other.

Workflow, subagents, skills or agent team

A workflow is the only one of the 4 where a script, not Claude, decides what runs next. Anthropic's own comparison:

Moving the plan into code also lets the script apply a quality pattern a single pass cannot: independent agents that try to disprove each other's findings before they are reported, or a plan drafted from several angles and weighed. Use a skill when Claude should follow a procedure; use a workflow when the work fans out wider than one context window.

3 ways to start one

Run /deep-research, type the keyword ultracode in a prompt, or ask for a workflow in plain words.

1. /deep-research <question> is the built-in workflow. It searches the web from several angles, fetches the sources, cross-checks them, votes on each claim and returns a cited report with the claims that failed cross-checking removed. A claim the verifiers could not check is marked unverified, not refuted.
2. The keyword, in a prompt you type: ultracode: audit every API endpoint under src/routes/ for missing auth checks. Claude writes a workflow for that task only. "Use a workflow to..." works the same way.
3. /effort ultracode turns it on for the whole session: Claude plans a workflow for every substantive task, sometimes several in a row (understand, change, verify). Each request then costs more tokens and time, so turn it off with /effort ultracode off for routine work.

The keyword only counts when a person types it. It does nothing in a prompt passed with -p, a scheduled task, or a webhook or pull request comment relayed into the session, so text from outside cannot start a fan-out.

Before the run starts, Claude Code shows the planned phases and asks: run it, view the raw script, or cancel. In auto mode it asks only on the first launch; in bypass mode and claude -p it does not ask, and an allow rule of Workflow or Workflow(<name>) approves runs there. The agents' own tool calls still go through your permission rules, so add the tools they need before a long run or it will stop on prompts.

What the script looks like

The script is plain JavaScript with top-level await: agent() starts one subagent, pipeline() one per item, parallel() a set at once. You rarely write it yourself, but you should be able to read what Claude wrote. A small one, from Anthropic's docs:

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 first agent returns JSON in the schema shape (Claude Code retries up to 5 times if it does not match). Each audit agent gets one file. An agent that is stopped or hits an unrecoverable error returns null, which is why the last line filters. Some rules the runtime enforces:

• No import(), no file or shell access from the script itself. Agents read, write and run commands; the script only coordinates them.
• No Date.now() or Math.random(). They throw, so that a relaunch makes the same agent() calls in the same order. Pass a timestamp in through args.
• No questions mid-run. For sign-off between stages, run each stage as its own workflow.
• Limits: 16 agents at once by default (CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS, 1 to 256), 4,096 items in one pipeline() or parallel() call, 1,000 agents a run.

Watching, stopping and relaunching

/workflows lists your runs; inside one, p pauses, x stops an agent or the run, r restarts an agent and s saves the script. Each phase shows its agent count, and each agent its prompt, recent tool calls, result and token use. A run that hits your subscription's usage limit waits for the reset and carries on by itself, up to twice. An agent that goes silent restarts from its prompt, up to 5 times.

Relaunching a stopped run is where the surprise is. Claude Code replays agents in the order they started: completed ones return their saved result, but a failed agent runs again together with every agent the script started after it, even ones that had finished. If agent 20 of 60 fails, relaunching reruns 41 agents, 40 of which had already done their work. Stopping a single agent with x counts as a failure; stopping the whole run does not.

Try itWhat a workflow runs, and what it runs again

Agents in the run

60

the runtime stops at 1,000

416 (default)64

Agent that fails

#20

First runLarge workflow

Shading changes with each wave of 16; the yellow square is agent 20, which failed.

After a relaunch

saved result, 19runs again, 41 in 3 waves

So put the agents most likely to fail (network calls, big files, flaky tests) late in the order, or split a long fan-out into separate workflows. Editing the script reruns everything from the first agent whose prompt changed.

Keeping the bill in check

A workflow can use far more tokens than doing the same job in conversation, and every token counts toward your plan's limits. Claude Code shows a Large workflow warning when a run schedules more than 25 agents or its projected total passes 1.5 million tokens; the warning does not stop it. What keeps the cost down:

• Try a small slice first: one directory, or a narrow question. /workflows shows each agent's tokens as it runs, and stopping usually keeps completed work.
• Set a size guideline in /config or workflowSizeGuideline: small (under 5 agents), medium (under 10, the default; small on Pro), large (under 50) or unrestricted. It is advice to Claude, not a cap.
• Name a smaller model for easy stages in your request. Otherwise every agent runs on your session's model.
• Let the cache work. Agents with the same model, tools and settings share a prompt cache prefix, and Claude Code holds the rest of a fan-out up to 5 seconds so they read the first agent's cache instead of each paying for it. That cache lasts 5 minutes unless you set subagentPromptCacheTtl to 1h.

Why Claude Code eats your limit covers where the rest of the tokens go, and Claude Code costs how usage is counted.

Save it, share it, or turn it off

A run that did what you wanted becomes a slash command: open it in /workflows and press s. Save it to .claude/workflows/ to share it with everyone who clones the repository, or to ~/.claude/workflows/ for yourself; it then runs as /<name>, and a saved workflow reads input from a global args, so "Run /triage-issues on issues 1024, 1025 and 1030" passes the list in. To share across repositories, put the script in a plugin's workflows/ folder; it runs as /<plugin>:<name>.

To turn workflows off, toggle Dynamic workflows in /config, set "disableWorkflows": true in your settings, or set CLAUDE_CODE_DISABLE_WORKFLOWS=1. An organisation sets disableWorkflows in managed settings. That also removes ultracode, and a run already in progress keeps going.