Claude Code Dynamic Workflows¶

A workflow is a JavaScript script Claude writes and the runtime executes to orchestrate subagents at scale, keeping intermediate results out of Claude's context.

How They Work¶

Dynamic workflows (research preview, requires Claude Code v2.1.154 or later) move the orchestration plan out of the conversation and into a script. You describe a task, Claude writes a JavaScript script that coordinates subagents, and a background runtime executes it while your session stays responsive. The script holds the loop, the branching, and the intermediate results; only the final answer returns to your context.

Reach for a workflow when a task needs more agents than one conversation can coordinate, or when the orchestration is worth codifying as something you can rerun — a codebase-wide bug sweep, a 500-file migration, or cross-checked research.

Workflows are available on all paid plans, the Anthropic API, Amazon Bedrock, Google Cloud Vertex AI, and Microsoft Foundry. On Pro, enable them from the Dynamic workflows row in /config.

Workflows vs Sub-Agents vs Skills¶

All three run a multi-step task; the difference is who holds the plan (source).

	Sub-Agents	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	Claude's context	Script variables
What's repeatable	The worker definition	The instructions	The orchestration itself
Scale	A few per turn	A few per turn	Dozens to hundreds per run
Interruption	Restarts the turn	Restarts the turn	Resumable in the same session

Because the script holds the intermediate results, the orchestrator's context stays clean no matter how many agents run — the lever that lets one run coordinate up to 1,000 agents. Moving the plan into code also lets a workflow apply a repeatable quality pattern, not just run more agents: independent agents can adversarially review each other's findings, or draft a plan from several angles and weigh them, before anything is reported.

Writing and Running a Workflow¶

The bundled /deep-research workflow is the quickest demonstration — it fans web searches across several angles, cross-checks the sources, votes on each claim, and returns a cited report (requires the WebSearch tool). To turn your own task into a workflow, include the word workflow in your prompt and Claude writes one instead of working turn by turn. Setting /effort ultracode (xhigh reasoning plus automatic workflow orchestration) lets Claude decide when a task warrants one.

Once a run does what you wanted, open /workflows, select it, and press s to save the script as a /<name> command — in .claude/workflows/ to share with the repo, or ~/.claude/workflows/ for personal use.

Runtime and Limits¶

The runtime executes the script in an isolated environment, separate from your conversation, and tracks each agent's result so a run is resumable within the same session. Resume only works in-session: exit Claude Code mid-run and the next session starts the workflow fresh. The runtime caps a run at up to 16 concurrent agents and 1,000 agents total, takes no mid-run user input (only agent permission prompts can pause it), and gives the script no direct filesystem or shell access — the agents read, write, and run commands; the script only coordinates them.

Subagents spawned by a workflow always run in acceptEdits mode and inherit your tool allowlist; tools outside the allowlist can still prompt mid-run.

Example¶

A bundled run needs only a question. The agents work in the background and one cited report lands when they finish:

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

For your own task, the workflow keyword routes a single prompt through the runtime instead of a turn-by-turn pass:

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

Claude writes the orchestration script, the approval prompt shows the planned phases, and the run proceeds in the background. If it does what you wanted, save it from /workflows with s so the same orchestration reruns on every branch.

When This Backfires¶

Token cost scales with agent count. A run that spawns dozens of agents can use far more tokens than working the same task in conversation. Every agent uses your session's model unless the script routes a stage elsewhere — check /model before a large run.
No mid-run sign-off. The runtime takes no user input mid-run, so a workflow cannot pause for approval between stages. For staged sign-off, run each stage as its own workflow.
Research preview. The feature and its limits may change; gate dependent automation behind a version check and confirm against the canonical docs.
Overkill for linear work. A task one conversation can hold needs sub-agents or agent teams, not the overhead of a script. Workflows earn their cost only when scale or repeatability is the point.

Key Takeaways¶

A workflow is a script Claude writes and a background runtime executes, moving the orchestration plan out of the conversation
Intermediate results live in script variables, so the orchestrator's context holds only the final answer — enabling up to 1,000 agents per run
The decision axis is who holds the plan: Claude turn-by-turn (sub-agents, skills) versus the script (workflows)
/deep-research is bundled; the workflow keyword or /effort ultracode has Claude write one; save a run as a /<name> command
Research preview (v2.1.154+); disable via /config, "disableWorkflows": true, or CLAUDE_CODE_DISABLE_WORKFLOWS=1