Orchestrate subagents at scale with dynamic workflows

Claude Code has launched dynamic workflows, a new feature that allows users to orchestrate subagents at scale through scripted automation. The tool, available in research preview on paid plans and major cloud platforms, enables tasks like codebase-wide bug sweeps and 500-file migrations by having Claude write and execute orchestration scripts while keeping the user's session responsive.

Documentation Index Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further. Dynamic workflows are in research preview. They require Claude Code v2.1.154 or later and are available on all paid plans, with Anthropic API access, and on Amazon Bedrock, Google Cloud Vertex AI, and Microsoft Foundry. On Pro, turn them on from the Dynamic workflows row in /config . subagents /docs/en/sub-agents 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. This page covers how to: - Decide when to use a workflow when-to-use-a-workflow instead of subagents or skills Run a bundled workflow run-a-bundled-workflow with /deep-research Have Claude write a workflow have-claude-write-a-workflow for your task and save it- Understand how a workflow runs how-a-workflow-runs and manage runs manage-runs When to use a workflow Subagents /docs/en/sub-agents , skills /docs/en/skills , and workflows can all run a multi-step task. The difference is who holds the plan: | Subagents | Skills | Workflows | | |---|---|---|---| | What it is | A worker Claude spawns | Instructions Claude follows | A script the runtime executes | | Who decides what runs next | Claude, turn by turn | Claude, following the prompt | The script | | Where intermediate results live | Claude’s context window | Claude’s context window | Script variables | | What’s repeatable | The worker definition | The instructions | The orchestration itself | | Scale | A few delegated tasks per turn | Same as subagents | Dozens to hundreds of agents per run | | Interruption | Restarts the turn | Restarts the turn | Resumable in the same session | Run a bundled workflow The quickest way to see a workflow in action is to run /deep-research , the built-in workflow bundled-workflows 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. 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.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 approve-the-plan-before-it-runs for the per-mode options.Watch progress The run starts in the background. Run 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 /workflows , use the arrow keys to select the run, and press Enter to open its progress view: Watch the run 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. have Claude write one have-claude-write-a-workflow , and once a run does what you wanted you can save it save-the-workflow-for-reuse as a command of your own. Bundled workflows Claude Code includes /deep-research as a built-in workflow: | Command | What it does | |---|---| /deep-research <question | Fans out web searches on a question across several angles, fetches and cross-checks the sources it finds, votes on each claim, and returns a cited report with claims that didn’t survive cross-checking filtered out. Requires the | Workflows you save save-the-workflow-for-reuse 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. | Key | Action | |---|---| ↑ / ↓ | Select a phase or agent | Enter or → | Drill into the selected phase, then into an agent to read its prompt, recent tool calls, and result | Esc | Back out one level | j / k | Scroll within the agent detail when it overflows | p | Pause or resume the run | x | Stop the selected agent, or stop the whole workflow when focus is on the run | r | Restart the selected running agent | s | | Have Claude write a workflow You can have Claude write a workflow for your task in two ways: Ask for a workflow ask-for-a-workflow-in-your-prompt in your prompt with the word workflow , and Claude writes one for the task. Let Claude decide with ultracode let-claude-decide-with-ultracode : set /effort ultracode and Claude plans a workflow for every substantive task in the session. bundled workflow bundled-workflows like /deep-research , or one you’ve saved save-the-workflow-for-reuse . Ask for a 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. save it as a command save-the-workflow-for-reuse afterward. If Claude Code highlights the word when you didn’t mean to trigger one, press alt+w to ignore it for this prompt. Let Claude decide with ultracode Ultracode is a Claude Code setting that combines xhigh reasoning effort /docs/en/model-config adjust-effort-level with automatic workflow orchestration. With it on, Claude plans a workflow for each substantive task instead of waiting for you to ask. /effort high when you return to routine work. It’s available on models that support xhigh effort /docs/en/model-config adjust-effort-level ; 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 : start, and skip this prompt for this workflow in this project from now on <name in <path 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 /docs/en/permission-modes : | Permission mode | When you’re prompted | |---|---| | Default, accept edits | Every run, unless you’ve selected Yes, and don’t ask again for that workflow in this project | | Auto | First launch only. Any Yes records consent in your user settings, and later launches start without prompting. Skipped entirely when ultracode is on | Bypass permissions, claude -p , Agent SDK | Never. The run starts immediately | Once , Always , and Deny actions. The progress view appears in the Background tasks side pane. Your permission mode controls only the launch prompt above. The subagents the workflow spawns always run in acceptEdits mode and inherit your tool allowlist /docs/en/settings permission-settings , regardless of your session’s mode. File edits are auto-approved. Shell commands, web fetches, and MCP tools that aren’t in your allowlist can still prompt you mid-run. To avoid this on a long run, add the commands the agents need to your allowlist before starting. In claude -p and the Agent SDK there is no one to prompt, so tool calls follow your configured permission rules without interactive confirmation. 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 /<name in future sessions from either location. If a project workflow and a personal workflow share a name, the project one runs. 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. The runtime tracks each agent’s result as the run progresses, which is what makes a run resumable resume-after-a-pause within the same session. Behavior and limits The runtime applies the following constraints:| Constraint | Why | |---|---| | No mid-run user input | Only agent permission prompts can pause a run. For sign-off between stages, run each stage as its own workflow | | No direct filesystem or shell access from the workflow itself | Agents read, write, and run commands. The script coordinates the agents | | Up to 16 concurrent agents, fewer on machines with limited CPU cores | Bounds local resource use | | 1,000 agents total per run | Prevents runaway loops | 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 If you stop a run, you can resume it: 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 Claude Code session. If you exit Claude Code while a workflow is running, the next session starts the workflow fresh. 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. You can stop a running workflow from /workflows at any time without losing completed work. Every agent in a workflow uses your session’s model unless the script routes a stage to a different one. 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 Turn workflows off Workflows are available in the CLI, the Desktop app, the IDE extensions, non-interactive mode /docs/en/headless with claude -p , and the Agent SDK /docs/en/agent-sdk/overview . 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. "disableWorkflows": true in managed settings /docs/en/server-managed-settings , or use the toggle on the Claude Code admin settings https://claude.ai/admin-settings/claude-code page. When workflows are disabled, the bundled workflow commands are unavailable, the workflow keyword no longer triggers a run, and ultracode is removed from the /effort menu. Related resources Run agents in parallel /docs/en/agents : compare subagents, agent view, agent teams, and workflows Create custom subagents /docs/en/sub-agents : the worker primitive workflows orchestrate Manage costs /docs/en/costs : how multi-agent runs count toward usage limits