Skip to main content
Dynamic workflows are available on all paid plans, with Anthropic API access, and on Amazon Bedrock, Google Cloud’s Agent Platform, and Microsoft Foundry. On Pro, turn them on from the Dynamic workflows row in /config.
A dynamic workflow is a JavaScript script that orchestrates subagents at scale. Claude writes the script for the task you describe, and a runtime executes it in the background while your session stays responsive. Reach for a workflow when a task needs more agents than one conversation can coordinate, or when you want the orchestration codified as a script you can read and rerun. Examples include a codebase-wide bug sweep, a 500-file migration, a research question that needs sources cross-checked against each other, and a hard plan worth drafting from several independent angles before you commit to one.

When to use a workflow

Subagents, skills, agent teams, and workflows can all run a multi-step task. The difference is who holds the plan: A workflow moves the plan into code. With subagents, skills, and agent teams, Claude is the orchestrator: it decides turn by turn what to spawn or assign next, and every result lands in a context window. A workflow script holds the loop, the branching, and the intermediate results itself, so Claude’s context holds only the final answer. Moving the plan into code also lets a workflow apply a repeatable quality pattern, not just run more agents: it can have independent agents adversarially review each other’s findings before they’re reported, or draft a plan from several angles and weigh them against each other, so you get a more trustworthy result than a single pass.

Run a bundled workflow

The quickest way to see a workflow in action is to run /deep-research, the built-in workflow Claude Code includes for investigating a question across many sources. You’ll see agents work through a set of phases in the background while your session stays free, and get one report at the end instead of a turn-by-turn transcript.
1

Run the workflow

Run /deep-research with a question you want investigated. It fans out web searches across several angles, fetches and cross-checks the sources it finds, and synthesizes a cited report.
2

Allow workflows

Claude Code asks whether to allow the workflow. Select Yes to continue. The exact prompt depends on your permission mode. See Approve the plan before it runs for the per-mode options.
3

Watch progress

The run starts in the background. Run /workflows, use the arrow keys to select the run, and press Enter to open its progress view:
The view shows each phase with its agent count, token total, and elapsed time. Drill into any phase to see its agents and what each one found. See Watch the run for the full set of controls.You can also watch from the task panel below the input box: a one-line progress summary appears there while the run is going. Press the down arrow to focus it, then Enter to expand.
4

Read the report

When the run finishes, the report lands in your session. It cites the sources each claim came from, with claims that didn’t survive cross-checking already filtered out.When the verifier agents can’t check a claim, such as after a rate limit or API error, the report lists that claim as unverified instead of counting it as refuted.
To run a workflow for your own task, have Claude write one, and once a run does what you wanted you can save it as a command of your own.

Bundled workflows

Claude Code includes /deep-research as a built-in workflow: /deep-research runs only when you invoke it. Workflows you save yourself become commands the same way and appear in / autocomplete alongside the bundled ones.

Watch the run

Workflows run in the background, so the session stays responsive while agents work. Run /workflows at any time to list running and completed workflows, then select one to open its progress view. The progress view shows each phase with its agent counts, token totals, and elapsed time. The footer lists the key for each action:

Have Claude write a workflow

You can have Claude write a workflow for your task in two ways:
  • Ask for a workflow in your prompt, either in your own words or by including the keyword ultracode, and Claude writes one for the task.
  • Let Claude decide with ultracode: set /effort ultracode and Claude plans a workflow for every substantive task in the session.
You can also run a workflow command that already exists: a bundled workflow like /deep-research, or one you’ve saved.

Ask for a workflow in your prompt

To run a single task as a workflow without changing the session’s effort level, include the keyword ultracode in your prompt. Asking in your own words, for example “use a workflow” or “run a workflow”, also works: Claude treats a direct request as the same opt-in. Before v2.1.160 the literal trigger keyword was workflow; natural-language requests work in both versions.
Claude Code highlights the keyword in your input and Claude writes a workflow script for the task instead of working through it turn by turn. The keyword only chooses how Claude structures the work: the agents’ tool calls receive the same permission checks and sandboxing as any other tool call in the session. If the run does what you wanted, you can save it as a command afterward. If you already have an orchestrator built another way, such as a folder of subagent prompts or a skill that fans work out, you can point Claude at it and ask for a workflow that does the same thing.

Dismiss or turn off the keyword

If you didn’t mean to start a workflow, press Option+W on macOS or Alt+W on Windows and Linux to dismiss the highlight for this prompt, or press backspace while the cursor is right after the highlighted keyword. To stop the keyword from triggering at all, turn off Ultracode keyword trigger in /config.

Where the keyword works

The keyword is an opt-in only in a prompt you type yourself: at the interactive prompt, in an IDE extension panel, in a Remote Control client, or in an Agent SDK application that stamps your keyboard input’s origin as { kind: "human" }. It doesn’t start a workflow when it reaches the session another way:
  • a prompt passed with -p
  • a prompt an Agent SDK application sends without stamping it as human input
  • a scheduled task prompt
  • a webhook payload or pull request comment relayed into the conversation
Before v2.1.210, the keyword started a workflow from any of these routes too, including a webhook payload or pull request comment relayed into the conversation.

Let Claude decide with ultracode

Ultracode is a Claude Code setting that combines xhigh reasoning effort with automatic workflow orchestration. With it on, Claude plans a workflow for each substantive task instead of waiting for you to ask.
To start a session with ultracode already on, launch with claude --effort ultracode. Requires Claude Code v2.1.203 or later. With ultracode on, Claude decides when a task warrants a workflow. A single request can turn into several workflows in a row: one to understand the code, one to make the change, and one to verify it. This applies to every task in the session, so each request uses more tokens and takes longer than at lower effort levels. /effort ultracode lasts for the current session; to have every session start with it, set the ultracode setting. Drop back with /effort high when you return to routine work. It’s available on models that support xhigh effort; on other models the /effort menu doesn’t offer it.

Approve the plan before it runs

In the CLI, the per-run prompt shows the planned phases and these options:
  • Yes, run it: start the run
  • Yes, and don’t ask again for <name> in <path>: start, and skip this prompt for this workflow in this project from now on. Claude Code offers this option when you run a bundled, saved, or plugin workflow by name, not for a script Claude wrote for the current task.
  • View raw script: read the script before deciding
  • No: cancel
Ctrl+G opens the script in your editor. Tab lets you adjust the prompt before the run starts. Whether you see this prompt depends on your permission mode: In claude -p and the Agent SDK, Claude Code never shows this prompt. It runs the Workflow tool call through the same permission evaluation as the rest of the session, so deny rules, ask rules, and dontAsk mode apply to the launch as they apply to every tool call. To let the workflow start in these runs, use one of these:
  • Permission rule: Workflow in your allow rules approves every workflow, and Workflow(<name>) approves one saved workflow by name.
  • Auto permission mode: the classifier reviews the call and can approve it.
  • Bypass permissions mode: Claude Code approves the call.
  • A PreToolUse hook: a hook that returns allow for the call approves it.
  • Your host: a --permission-prompt-tool approves it, or, with the Agent SDK, a canUseTool callback or a PermissionRequest hook approves it.
In the Desktop app, an approval card shows the workflow name, the phase list, and a token-usage caution, with Once, Always, and Deny actions. The progress view appears in the Background tasks side pane. The subagents the workflow spawns use your permission rules, and Claude Code picks their permission mode by the rules under which permission mode a subagent runs in. To avoid prompts on a long run, add the tools the agents need to your allow rules before starting.

Save the workflow for reuse

When Claude writes a workflow for a task you’ll repeat, you can save that run’s script as a command. A process like a review you run on every branch then runs the same orchestration each time. Run /workflows, select the run you want to keep, and press s. In the save dialog, Tab toggles between the two save locations:
  • .claude/workflows/ in your project: shared with everyone who clones the repo
  • ~/.claude/workflows/ in your home directory: available in every project, visible only to you. If you set CLAUDE_CONFIG_DIR, this location is the workflows/ directory under that path.
The save dialog shows the resolved path for the personal location. Press Enter to save. The workflow runs as /<name> in future sessions from either location. Claude Code checks the save location for symlinks before writing, and shows an error instead of writing through one. What it checks depends on where you save:
  • Project location: Claude Code refuses if .claude, .claude/workflows, or the target file is a symlink.
  • Personal location: Claude Code refuses only if the target file itself is a symlink, so a ~/.claude directory managed by a dotfiles tool still works.
Before v2.1.216, Claude Code followed the link, which could place the file outside the location you chose. In a monorepo with several .claude/ directories, you can keep workflows alongside the package they apply to. As of v2.1.178, saving to the project location writes to the closest .claude/workflows/ directory that already exists between your working directory and the repository root, or to the repository root if none exists yet. Project workflows also load from every .claude/workflows/ along that path, and when more than one defines the same name Claude Code runs the one closest to the working directory. If a project workflow and a personal workflow share a name, the project one runs.

Distribute a workflow in a plugin

To share a workflow across teams or repositories, include it in a plugin. Place the script in a workflows/ directory at the plugin root, or point to a different location with the workflows manifest field. Plugin workflows are namespaced by the plugin name. A plugin called acme-tools containing a script whose meta.name is release-audit runs as /acme-tools:release-audit.

Pass input to a saved workflow

A saved workflow can accept input through the args parameter. The script reads it as a global named args. Use this to supply a research question, a list of target paths, or a configuration object at invocation time instead of editing the script for each run. The following prompt runs a saved workflow with a list of issue numbers:
Claude passes the list as structured data, so the script can call array and object methods on args directly without parsing it first. If args is omitted, the global is undefined inside the script.

Example workflow prompts

A workflow fits best when the task is larger than one agent can hold in context, or when the same step needs to run across many items. The prompts below show common shapes. Each one asks Claude to write and run a workflow for that task; you don’t write the script yourself.

Audit many files for the same issue

Fan out one agent per file, then collect and verify the findings.

Keep fixing until a check passes

Run a checker, fix what failed, and repeat until it passes or stops making progress.

Migrate many files in parallel

Discover the files to migrate, transform each one in an isolated copy so edits don’t conflict, and verify each result.

Review every changed file and write one summary

Run a reviewer per file, then hand all the findings to one agent that ranks and deduplicates them.

Research a topic across many sources

Fan out readers across changelogs, issues, and docs, then synthesize. The bundled /deep-research workflow does this; you can also describe a narrower version.

Find issues until the list stops growing

Keep searching in rounds and stop when new rounds turn up nothing new.

What the saved script looks like

When you save a workflow, the file in .claude/workflows/ holds a meta block followed by a script body that orchestrates subagents. You usually don’t need to edit it, but here is the shape of a small one so you can recognize what Claude generated:
The body is plain JavaScript with top-level await. agent() spawns one subagent, pipeline() runs one per item in a list, and parallel() runs a set of agent tasks at the same time and waits for all of them. An agent() call resolves to null if you stop it mid-run or it hits an unrecoverable API error. pipeline() keeps that null in the results array, which is why the example ends with .filter(Boolean) to drop those entries.

Edit a saved script

To change a workflow you saved, edit its .js file or ask Claude to make the change. Before you edit or ask, run the /workflow-authoring bundled skill to load the script-writing reference Claude works from. The skill requires Claude Code v2.1.248 or later. To run the edited version in the current session, run /reload-skills to re-read the workflow directories, then run /<name> again. Claude Code applies these rules to each part of the file when it loads and runs the script:
  • meta block: keep export const meta as the first statement, and keep it a plain object literal with a name and a description. If it contains anything other than literal values, such as a variable, a function call, or a spread, Claude Code drops /<name> from / autocomplete.
  • Body: besides agent(), pipeline(), and parallel(), you can call phase() to group the agents that follow under a title in the progress view, call log() to show a message above the phases, and read the args global. If the body has a syntax error, Claude Code reports it when you run the workflow.
  • phases: if you list them in meta, give each entry exactly the title you pass to phase(). A phase() title with no entry gets a progress group of its own.
  • Timestamps and randomness: Claude Code makes Date.now(), Math.random(), and a no-argument new Date() throw inside the script, so that a relaunched run repeats the same agent() calls. Pass a timestamp in through args instead.
You can also edit the script of a single run rather than the saved copy. Resume after a pause covers which agents run again when you relaunch an edited script. For the Workflow tool’s inputs, see its entry in the Agent SDK reference.

How a workflow runs

The workflow runtime executes the script in an isolated environment, separate from your conversation. Intermediate results stay in script variables instead of landing in Claude’s context. Every run writes its script to a file under your session’s directory in ~/.claude/projects/. Claude receives the path when the run starts, so you can ask for it. You can open that file to read the orchestration Claude wrote, diff it against a previous run’s script, or edit it and ask Claude to relaunch from the edited version. Claude can start a workflow only from a script file the session is already allowed to read. To run a script kept outside your working directory, add its directory with /add-dir or a Read allow rule first. The runtime tracks each agent’s result as the run progresses, which is what makes a run resumable within the same session.

Prompt caching in a fan-out

Agents in the same run can read each other’s prompt cache. Two agents that run with the same model, effort level, agent type, tools, output schema, and working directory build the same tools-and-system-prompt prefix, so an agent that starts after a matching sibling’s response has begun reads that sibling’s cache on its first request. A workflow agent’s requests fall outside the main conversation’s cache TTL bucket, so its cache holds for five minutes by default, including on a Claude subscription. To keep it for an hour, set subagentPromptCacheTtl to 1h. The API bills 1-hour cache writes at a higher rate. When a fan-out starts several matching agents at once, Claude Code holds all but the first until the first agent’s response begins, then releases the held agents together so their first requests read the shared prefix instead of each processing it uncached. Claude Code caps the hold at CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS milliseconds, 5000 by default. Set it to 0 to disable the hold.

Behavior and limits

The runtime applies the following constraints:

Manage runs

Once a run starts, you manage it from the /workflows view, or by expanding its progress line in the task panel below the input box.

Resume after a pause

Resume a paused run from /workflows by selecting it and pressing p. For a run you stopped, ask Claude to relaunch the workflow with the same script. Claude Code replays the run in the order agents started, and each agent either returns its saved result or runs again:
  • Completed: returns its saved result. The first agent whose prompt differs from the previous run, because you edited the script or an earlier agent returned something different, runs again, and so does every agent after it, even ones that completed.
  • Still running when you stopped: starts over. Stopping the whole run doesn’t count any agent as failed.
  • Failed: runs again, and so does every agent that started after it, even ones that completed. Stopping one agent alone, by selecting it in /workflows and pressing x, counts as failing.
That last case means a failure in the middle of a fan-out reruns work that already finished. If a script starts A, B, C, and D in that order and B fails, relaunching returns A from cache and runs B, C, and D again. You can resume a run within the same Claude Code session. What happens to a running workflow when you leave the session depends on how you leave:
  • If you background the session, Claude Code replays the run the same way in the background session and continues it.
  • If you exit Claude Code while a workflow is running and agent view is on, the exit dialog offers Move to background and exit, which carries the run over the same way. If you choose Exit and stop tasks instead, or the option isn’t offered, the run stops with the session. Claude Code keeps the run’s saved results under that session’s directory in ~/.claude/projects/, so a session you resume with claude --resume can replay them when you ask Claude to relaunch the workflow, while a session you start fresh has nothing to replay and starts the workflow over.

Cost

A workflow spawns many agents, so a single run can use meaningfully more tokens than working through the same task in conversation. Runs count toward your plan’s usage and rate limits like any other session. To gauge the spend before committing to a large task, run the workflow on a small slice first: one directory instead of the whole repo, or a narrow question instead of a broad one. The /workflows view shows each agent’s token usage as the run progresses, and you can stop the run there at any time, usually without losing completed work. Resume after a pause covers what a stopped run keeps. The runtime’s agent caps limit how many agents a single run can spawn, which bounds the cost of a runaway script. To keep runs to fewer agents, choose the small size guideline. Claude Code also flags a run that grows unusually large. When a workflow schedules more than 25 agents, or its projected token total passes 1.5 million, its progress line in the task panel below the input box shows a Large workflow warning. The warning points you to /workflows, where you can stop the run. The warning is advisory: it doesn’t pause or limit the run. Two settings change when you see it:
  • If you choose a size guideline yourself, its agent count replaces the 25-agent threshold. The built-in default guideline leaves the threshold at 25.
  • Sessions with ultracode on don’t show the warning, because turning ultracode on already opts you in to large runs.
Every agent in a workflow uses your session’s model unless the script routes a stage to a different one or the CLAUDE_CODE_SUBAGENT_MODEL environment variable is set, which overrides both. To control the model cost:
  • Check /model before a large run if you usually switch to a smaller model for routine work
  • Ask Claude to use a smaller model for stages that don’t need the strongest one when you describe the task
When your organization’s availableModels allowlist blocks a model the script requests for an agent, that agent runs on a substituted model instead, following the same substitution rules as subagents. The run’s progress view in /workflows shows a warning naming both the requested and substituted models.

Set a size guideline

A size guideline tells Claude how many agents to aim for when it writes a dynamic workflow. Claude Code sends the guideline to Claude as advice, not a cap, so a prompt that calls for a different scale still overrides it. Requires Claude Code v2.1.202 or later. Each value maps to an agent count: The default is medium. Until you choose a value, the /config row shows medium (default) and the workflow’s Running in background line shows medium size (/config). Requires Claude Code v2.1.219 or later; earlier versions default to unrestricted. To change the guideline, pick a value for the Dynamic workflow size setting in /config, or run /config workflowSizeGuideline=small. On v2.1.219 and later, you can also set the workflowSizeGuideline key in any settings file; that value takes precedence over /config, and Claude Code hides the /config row while a settings file provides one. Changes take effect on the next prompt. The runtime agent caps still apply regardless of the setting.

Turn workflows off

Workflows are available in the CLI, the Desktop app, the IDE extensions, non-interactive mode with claude -p, and the Agent SDK. The same disable settings apply on every surface. To turn workflows off for yourself:
  • Toggle Dynamic workflows off in /config. Persists across sessions.
  • Set "disableWorkflows": true in ~/.claude/settings.json. Persists across sessions.
  • Set CLAUDE_CODE_DISABLE_WORKFLOWS=1. Read at startup, so it applies wherever you set it.
To turn workflows off for your whole organization, set "disableWorkflows": true in managed settings, or use the toggle on the Claude Code admin settings page. When workflows are disabled, the bundled workflow commands and the /workflow-authoring skill are unavailable, the ultracode keyword no longer triggers a run, and ultracode is removed from the /effort menu.