Dynamic workflows in Claude Code, your first orchestrated multi-agent script

Since the Opus 4.8 release Claude Code can do something that was missing before. You describe a large task, and Claude does not just write you the answer but a JavaScript script that orchestrates dozens of subagents in the background. That is called dynamic workflows, has been available since version 2.1.154 and is still in research preview. I will show you in 20 minutes how to run your first workflow without your token bill exploding. We build this up carefully, first the built-in workflow to watch, then one of your own.

Step 1, check your prerequisites

Dynamic workflows need Claude Code v2.1.154 or newer. Type claude --version into your terminal and look. If you are older, update first, otherwise the whole mechanism does not show up at all.

Workflows are available on all paid plans, via the Anthropic API and on Amazon Bedrock, Google Cloud Vertex AI and Microsoft Foundry. If you are on the Pro plan they are not on automatically. You switch them on via the "Dynamic workflows" line in /config. On Max and the larger plans they run straight away.

Take this check seriously. On my first attempt I spent ten minutes looking for why the keyword did nothing, and it was simply an old version.

Step 2, understand when a workflow is the right tool

Claude Code has four ways to handle a multistep task. Subagents, skills, agent teams and workflows. The difference is only one thing, namely who holds the plan.

With subagents, skills and agent teams Claude is the conductor. It decides move by move what happens next, and every intermediate result lands in its context window. A workflow moves the plan into code. The script holds the loop, the branches and the intermediate results itself, and only the finished answer lands in Claude's context.

Reach for a workflow when a task needs more agents than a single conversation can coordinate. A bug sweep across the whole repo. A migration over 500 files. A research question where sources should be cross-checked against each other. Or a difficult plan you want designed from several independent angles before you commit. For three delegated tasks per turn you stay with subagents, a workflow is overkill for that.

Step 3, run the built-in /deep-research workflow first

Before you build something yourself, see what a workflow feels like. Claude Code ships /deep-research as a ready-made workflow. It fans web searches out across several angles, fetches and cross-checks the sources against each other, votes on every claim and gives you a report with citations at the end.

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

Claude Code now asks whether it may run the workflow. Choose Yes. The run starts in the background, your session stays free. You do not have to wait and twiddle your thumbs, you can keep working while the agents run in the background. Important here, /deep-research needs the WebSearch tool, otherwise it has no sources.

Step 4, watch the run with /workflows

Type /workflows and you see all running and finished workflows. Arrow keys to select, enter to go in.

/workflows

The progress view shows you every phase with agent count, token total and elapsed time. You can drill into a phase with enter and see what each individual agent found. The most important keys are in the footer, a few are worth remembering. p pauses or resumes the run. x stops a single agent, or the whole workflow when the focus is on the run. r restarts a hanging agent. s saves the run's script as its own command, we will get to that.

Step 5, have Claude write a workflow for your task

Now your own workflow. The simplest way is to put the keyword ultracode in your prompt. Then Claude writes a script for the task instead of working through it move by move.

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

Claude Code highlights the keyword in your input and gets going. Your own words work too, "use a workflow" or "run a workflow" is treated by Claude as the same consent. A small note on versions, before v2.1.160 the literal trigger keyword was workflow, natural-language requests work in both versions. If you typed the keyword by accident, press option and W on a Mac or alt and W on Windows and Linux, and the highlight disappears for that prompt.

If you want to work in workflow mode permanently, set /effort ultracode. That combines xhigh reasoning with automatic orchestration, Claude then plans a workflow itself for every larger task in the session. But it eats noticeably more tokens and takes longer. I go back down with /effort high as soon as I am back on routine work.

Step 6, approve the plan before it runs

In the CLI Claude shows you the planned phases and a few options before every run. Yes starts it. Yes and do not ask again remembers your consent for exactly this workflow in this project. View raw script shows you the script before you decide, Ctrl+G opens it directly in your editor. With tab you can still adjust the prompt before it starts.

Read the script the first time round, genuinely. A workflow is code Claude wrote, and you want to see what it runs across your files before it does. Incidentally, the subagents a workflow spawns always run in acceptEdits mode and inherit your tool allowlist, regardless of your session's mode. File edits are therefore waved through automatically. Shell commands, web fetches and MCP tools that are not in your allowlist can still ask you mid-run.

Step 7, know the limits

Workflows have hard limits, and that is a good thing. There is no mid-run input, only agents' permission prompts can pause a run. If you want to approve between two stages yourself, build each stage as its own workflow. The script itself has no direct access to the filesystem or the shell, the agents do that, the script only coordinates them.

Plus two numbers worth keeping in mind. Up to 16 agents run at the same time, fewer on machines with few CPU cores. And a maximum of 1000 agents per run is allowed, which prevents infinite loops. If your workflow runs into that wall, the task was probably cut wrong.

Step 8, keep the cost small

A workflow spawns many agents, a single run can eat considerably more tokens than the same task in a normal conversation. The runs count against your plan quota and your rate limits like anything else.

My standard trick is to test on a small slice first. One directory instead of the whole repo. A narrow question instead of a broad one. In the /workflows view you see the token consumption of every agent while the run is going, and you can abort at any time with x without losing the work already done. If you otherwise switch to a smaller model for routine work, check /model before a large run. You can also tell Claude to use a smaller model for simple stages.

Step 9, save the workflow as a reusable command

When Claude has written a workflow for a task you repeat, saving is worth it. A review you run on every branch then runs the same orchestration every time.

Type /workflows, select the run you want to keep, and press s. In the save dialog you switch between two locations with tab. .claude/workflows/ in the project is shared with everyone who clones the repo. ~/.claude/workflows/ in your home directory is there in every project, but visible only to you. Enter saves. From then on the workflow runs as /<name> in future sessions.

A saved workflow can take input via the args parameter. The script reads it as a global variable called args. That way you feed in a research question, a list of paths or a config object without touching the script every time.

> Run /triage-issues on issues 1024, 1025, and 1030

Claude passes the list through as structured data, so the script can call array and object methods on args directly.

Step 10, switch them off again when needed

Workflows are not for every day. If the automatic orchestration gets in your way, you switch it off via the "Dynamic workflows" toggle in /config, which persists across sessions. Alternatively you set "disableWorkflows": true in ~/.claude/settings.json or the environment variable CLAUDE_CODE_DISABLE_WORKFLOWS=1. For a whole team that goes through the managed settings.

With that you have the full circle. You know the built-in /deep-research, you let Claude write your own workflows, you keep cost and limits under control and you save what repeats. If you want to understand next how the individual subagents a workflow orchestrates behave, continue with the playbook Structuring a subagent team and the lesson Research, critic, analyst. For the bigger cost picture, Claude Code cost controls for the daily driver fits.

Source

All commands, version numbers and limits in this playbook come from the official Claude Code documentation, as of June 2026. The main source is the page Orchestrate subagents at scale with dynamic workflows. The Opus 4.8 release and the version number v2.1.154 are in the Claude Code release notes. Since dynamic workflows run as a research preview, individual key bindings and defaults may still change, so check the linked docs when in doubt.