Dynamic Workflows#

Dynamic Workflows are in research preview. They require Claude Code v2.1.154 or later and are available on all paid plans.

What are Dynamic Workflows#

A dynamic workflow is a JavaScript script that orchestrates subagents at scale. Claude writes the script for the task you describe, and a dedicated runtime executes it in the background while your session stays responsive.

The key architectural insight is where the plan lives. With subagents or Agent Teams, Claude acts as the orchestrator: it decides turn by turn what to spawn, and every intermediate result lands in Claude's context window. With a dynamic workflow, the orchestration plan moves into executable code. The script holds the loop, the branching logic, and the intermediate results itself — so Claude's context only needs to hold the final answer, not every intermediate step. 1

This separation unlocks a scale that turn-by-turn orchestration cannot reach: from dozens to hundreds of agents per single run, up to a hard limit of 1,000 agents. It also makes the orchestration itself repeatable — once a run does what you wanted, you can save the script as a command and run the same orchestration again without prompting Claude to reconstruct it.

Beyond raw scale, workflows enable repeatable quality patterns that go beyond simply running more agents. A script can route findings through an independent adversarial review phase before they are reported, or draft a plan from several competing angles and weigh them against each other. This produces a more trustworthy result than a single pass through the same context. 1

Reach for a dynamic workflow when:

• A task needs more agents than a single conversation can coordinate
• You want the orchestration codified as a script you can read and rerun
• You need an automated quality pattern applied consistently across the result (e.g., cross-checking claims between sources before including them)

Examples include a codebase-wide bug sweep, a 500-file migration, a research question that needs sources cross-checked against each other, or a hard architectural decision worth drafting from several independent angles before you commit to one. 1

How Dynamic Workflows Differ from Agent Teams#

Dynamic Workflows and Agent Teams are both multi-agent approaches, but they place the orchestration logic in fundamentally different places.

Agent Teams have Claude as the orchestrator. A lead session decides turn by turn what to spawn, coordinates a shared task list, and synthesizes results. Every finding flows back through Claude's context, and the lead can steer the team based on what teammates report in real time. This is well-suited for complex work where teammates need to message each other directly, challenge each other's hypotheses, or where you want to redirect individual teammates mid-run. 2

Dynamic Workflows move the orchestration plan into executable code. The script — written by Claude and executed by the workflow runtime — holds the loop, the branching, and the intermediate results. Claude's context holds only the final output. The script runs autonomously; there is no turn-by-turn lead deciding what to do next. 1

The table below, drawn from the official documentation, shows where workflows fit alongside the other approaches: 1

The practical choice between them:

• Use Agent Teams when your workers need to communicate directly with each other, when you want to steer individual teammates mid-run, or when the task benefits from collaborative discussion and competing hypotheses. Agent Teams are experimental and require the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable. 2
• Use Dynamic Workflows when scale matters (dozens to hundreds of agents), when you want the orchestration to be repeatable as a saved command, or when the task can be fully specified upfront and benefits from a structured, scripted quality pattern applied consistently. Workflows are in research preview and available on all paid plans. 1

How to Trigger a Dynamic Workflow#

There are three ways to start a dynamic workflow: running a bundled workflow command, asking Claude with the workflow keyword, or enabling ultracode mode for automatic workflow planning.

Bundled workflows: /deep-research#

The quickest way to see a workflow in action is to run /deep-research, the built-in workflow for investigating a question across many sources. 1

Step 1 — Run the workflow

Pass a question as the argument:

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

The workflow fans out web searches across several angles, fetches and cross-checks the sources it finds, and synthesizes a cited report.

Step 2 — Allow the workflow

Claude Code asks whether to allow the workflow. Select Yes to continue. Whether you see this prompt depends on your permission mode:

Press Ctrl+G to open the raw script in your editor before deciding. Press Tab to adjust the prompt before the run starts.

Step 3 — Watch progress

The run starts in the background. Open the progress view at any time:

/workflows

Use the arrow keys to select the run and press Enter to expand it. The view shows each phase with its agent count, token total, and elapsed time. Drill into any phase to see individual agents and what each one found. A one-line summary also appears in the task panel below the input box while the run is active.

Step 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.

Ask Claude: include "workflow" in your prompt#

To run a single task as a workflow without changing the session's effort level, include the word workflow anywhere in your prompt: 1

Run a workflow to audit every API endpoint under src/routes/ for missing auth checks

Claude Code highlights the word in your input. Claude then writes a workflow script for the task instead of working through it turn by turn. If you didn't intend to trigger a workflow, press alt+w to ignore the keyword for that prompt.

Once the run completes, you can save the script as a reusable command from /workflows by pressing s.

Ultracode mode: /effort ultracode#

Ultracode is a session-level setting that combines xhigh reasoning effort with automatic workflow orchestration. With it on, Claude plans a workflow for every substantive task instead of waiting for you to ask: 1

/effort ultracode

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. Because this applies to every task in the session, each request uses more tokens and takes longer than at lower effort levels.

Ultracode lasts for the current session and resets when you start a new one. Drop back with /effort high when you return to routine work. It is available on models that support xhigh effort; the /effort menu does not show the ultracode option on other models.

Built-in Guardrails and Limits#

The workflow runtime applies a set of constraints to keep runs safe, predictable, and bounded in resource use. 1

Resumable runs#

If you stop a run, you can resume it within the same Claude Code session: agents that already completed return their cached results, and the rest run live. Resume a paused run from /workflows by selecting it and pressing p, or ask Claude to relaunch the workflow with the same script.

Resume works within the same session only. If you exit Claude Code while a workflow is running, the next session starts the workflow fresh — completed work is not cached across sessions. 1

Background execution and session responsiveness#

Workflows run in the background, so you can continue using your Claude Code session — asking questions, running commands, or starting new conversations — while agents work. The task panel below the input box shows a live one-line summary of the active run. 1

Subagent permissions#

Subagents spawned by a workflow always run in acceptEdits mode and inherit your session's tool allowlist. File edits are auto-approved. Shell commands, web fetches, and MCP tools that are not in your allowlist can still prompt you mid-run. To avoid interruptions on long runs, add the commands the agents need to your allowlist before starting. 1

In claude -p and the Agent SDK there is no interactive user to prompt, so tool calls follow your configured permission rules without interactive confirmation.

Use Cases#

Dynamic workflows are most effective when a task has a large, well-defined scope that benefits from parallelism and where the orchestration plan can be fully specified upfront. The following scenarios illustrate the range of problems they handle well. 1

Codebase audits#

Scan every file in a module — or every API route in a service — for a specific category of issue. Each agent handles a slice of the codebase independently, and the workflow collects and deduplicates findings across all of them.

Run a workflow to audit every API endpoint under src/routes/ for missing auth checks

Large-scale migrations#

Automated migrations across hundreds of files — changing an import path, updating an API call signature, renaming a constant — are a natural fit. The workflow assigns each file or module to an agent, tracks which have been updated, and handles failures without losing completed work.

A 500-file migration that would take many sequential turns to coordinate fits into a single workflow run.

Cross-checked research#

When you need to investigate a question across many independent sources, a workflow can fan out searches in parallel and then route findings through a cross-checking phase before synthesizing a final report. Claims that appear in only one source can be flagged or filtered out.

The /deep-research bundled workflow demonstrates this pattern directly. 1

Codebase-wide bug sweeps#

Systematic testing or analysis across many modules — checking for a class of vulnerability, verifying that every exported function has a test, or confirming that all error paths are handled — benefits from true parallelism. A workflow can route each module to a dedicated agent, aggregate results, and return a consolidated report.

Research questions with adversarial cross-checking#

For questions where accuracy matters, a workflow can assign multiple agents to investigate the same question from different angles, then have independent agents review and challenge each other's findings before they are included in the final answer. The result is more trustworthy than a single linear investigation because no single agent's blind spots determine what gets reported. 1

Saving and reusing orchestration patterns#

Once a workflow run does what you wanted, save it as a named command from the /workflows view (s key). A code review pattern you run on every branch, a migration template, or a research format you return to regularly can then be launched with a single / command — applying the same orchestration each time without prompting Claude to reconstruct it. 1

Built-in Example: /deep-research#

The /deep-research workflow is the bundled workflow included with Claude Code. It demonstrates the core dynamic workflow pattern — fan-out, parallel fetch, cross-checking, synthesis — applied to a research question. 1

What it does#

Given a research question, /deep-research works through a sequence of phases entirely in the background:

1. Search fan-out — Fans out web searches across several angles of the question simultaneously, covering more of the search space than a linear investigation would.
2. Source fetch — Fetches the sources identified in the search phase, each in its own agent.
3. Cross-checking — Checks claims from each source against claims from the others. Claims that appear in only one source, or that contradict the majority, are flagged.
4. Credibility voting — Agents vote on each claim's credibility based on the cross-check results.
5. Synthesis — Returns a single cited report with claims that didn't survive cross-checking already filtered out.

The result is a cited report you can read in one place, rather than a turn-by-turn transcript of search results. 1

Requirements and usage#

/deep-research requires the WebSearch tool to be available in your session.

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

Saving custom workflows#

Any workflow run — including runs triggered by asking Claude or via ultracode mode — can be saved as a named command. Saved workflows appear in / autocomplete alongside the bundled /deep-research command, so your own orchestration patterns become first-class commands. 1

If a project workflow and a personal workflow share a name, the project-level one (stored in .claude/workflows/) takes precedence over the personal one (stored in ~/.claude/workflows/).

Requirements#

Dynamic Workflows are in research preview. The following prerequisites apply: 1

Enabling workflows on Pro#

On the Pro plan, enable Dynamic Workflows from the Dynamic workflows row in /config.

Disabling workflows#

Workflows can be turned off at the user or organization level:

• User: toggle Dynamic workflows off in /config, or set "disableWorkflows": true in ~/.claude/settings.json, or set the environment variable CLAUDE_CODE_DISABLE_WORKFLOWS=1.
• Organization: set "disableWorkflows": true in managed settings, or use the toggle on the Claude Code admin settings page.

When disabled, the bundled workflow commands become unavailable, the workflow keyword no longer triggers a run, and ultracode is removed from the /effort menu. 1

Best Practices for Safe Usage#

Dynamic workflows can spawn hundreds of agents in a single run. The guidance below helps you get useful results without unexpected token costs or runaway runs.

Scope workflows to a specific, well-defined task#

Workflows are most effective — and most economical — when the task is clearly bounded. A workflow asked to "audit the entire codebase" with no further constraints will interpret that as broadly as it can. A workflow asked to "audit every exported function in src/api/ for missing input validation" has a clear scope and a clear stopping condition.

Write your workflow prompt the same way you would write a good acceptance criterion: what needs to be checked, what the pass/fail condition is, and where the boundary of the task is. 1

Start small and scale up#

Run /deep-research on a narrow question before using ultracode on a large codebase. Run a workflow over a single module before running it over a repository. Starting small lets you verify that the workflow does what you intended before committing to a large token spend. 1

Check your model before large runs#

Every agent in a workflow uses your session's model unless the script explicitly routes a stage to a different one. If you usually switch to a smaller model for routine work, check /model before launching a large run. You can also ask Claude — when you describe the task — to use a smaller model for phases that don't need the strongest one. 1

Pre-approve tool access to avoid mid-run interruptions#

Shell commands, web fetches, and MCP tools that are not in your allowlist can pause a long-running workflow with permission prompts. Add the commands the agents will need to your tool allowlist before starting, rather than approving them one by one mid-run. 1

Monitor progress and stop early if needed#

The /workflows view shows each phase with its agent count, token total, and elapsed time. You can drill into any phase or individual agent to see what it is doing. If the run is going in the wrong direction — producing low-quality results, exploring the wrong part of the codebase, or consuming more tokens than expected — stop it from /workflows at any time.

Stopping does not lose completed work. When you resume within the same session, agents that already completed return their cached results and only the remaining agents run live. 1

Treat ultracode as a high-effort mode, not a default#

Ultracode applies workflow orchestration to every substantive task in the session and combines it with xhigh reasoning effort. A single request can turn into several workflows in sequence. This produces high-quality results but uses significantly more tokens than lower effort levels.

Use ultracode for your highest-stakes work — a complex migration, a thorough security audit, a decision you need thoroughly analyzed from multiple angles. Use /effort high or lower for routine tasks. Ultracode resets when you start a new session, so the cost is bounded to the session in which you enable it. 1

Related resources#

• Run agents in parallel — compare subagents, agent view, agent teams, and workflows
• Create custom subagents — the worker primitive workflows orchestrate
• Manage costs — how multi-agent runs count toward usage limits
• Orchestrate teams of Claude Code sessions — the turn-by-turn alternative to dynamic workflows