Using Claude Code Dynamic Workflows

Dynamic workflows are one of the more misunderstood features in Claude Code, partly because the name invites comparisons to static CI pipelines and YAML-based agentic workflows. They are something quite different. 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. This tutorial walks through what they are, when to use one, and how to drive them in practice. It is based on the official Claude Code documentation at code.claude.com/docs/en/workflows.

Note up front: 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 you turn them on from the Dynamic workflows row in /config.

What a dynamic workflow actually is

The key idea is where the plan lives. With subagents, skills, and agent teams, Claude is the orchestrator: it decides turn by turn what to spawn or assign next, and every intermediate result lands in a context window. A workflow moves the plan into code. The script holds the loop, the branching, and the intermediate results in script variables, so Claude's context only ever holds the final answer.

That distinction is what makes workflows scale. A single conversation can coordinate a few delegated tasks per turn; a workflow can run dozens to hundreds of agents in a single run, up to a hard cap of 1,000 agents, with up to 16 running concurrently.

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 and how repeatable the orchestration is. 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.

• A codebase-wide bug sweep across many files
• A large migration touching hundreds of files
• A research question where sources must be cross-checked against each other
• A hard plan worth drafting from several independent angles before committing to one

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 are reported, or draft a plan from several angles and weigh them against each other, giving you a more trustworthy result than a single pass.

The quickest way to see one: /deep-research

Claude Code ships with one bundled workflow, /deep-research, for investigating a question across many sources. It fans out web searches across several angles, fetches and cross-checks the sources it finds, votes on each claim, and synthesises a cited report with claims that did not survive cross-checking filtered out.

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

The run starts in the background. Run /workflows, select the run with the arrow keys, and press Enter to open its progress view — you will see each phase with its agent count, token total, and elapsed time, and you can drill into any agent to read its prompt and result.

Having Claude write a workflow for your task

You do not write the script yourself. You describe the task and Claude writes the orchestration. The simplest opt-in is to include the keyword ultracode in your prompt (asking in plain English, like 'use a workflow', works too; on Claude Code versions before v2.1.160 the literal keyword was workflow):

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

Claude highlights the keyword and writes a workflow script for the task instead of working through it turn by turn. Before it runs, you are shown the planned phases and can choose to run it, view the raw script, adjust the prompt, or cancel. If you would rather let Claude decide on its own, set /effort ultracode and it will plan a workflow for every substantive task in the session — powerful, but it uses more tokens, so drop back to /effort high for routine work.

Saving a workflow for reuse

When a run does what you wanted, you can keep it. Run /workflows, select the run, and press s. You choose where to save it:

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

Saved workflows become slash commands that appear in autocomplete alongside the bundled ones. They can also accept input through an args global, so you can pass a research question or a list of target paths at invocation time instead of editing the script:

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

How a run behaves, and its limits

The runtime executes the script in an isolated environment, separate from your conversation, and writes the script to a file under your session's directory in ~/.claude/projects/ so you can read, diff, or edit it. A few constraints are worth internalising before you lean on workflows:

• No mid-run user input — only agent permission prompts can pause a run, so for sign-off between stages, run each stage as its own workflow
• The agents run in acceptEdits mode and inherit your tool allowlist, so their file edits are auto-approved; only shell, web, or MCP calls outside that allowlist can still prompt you mid-run
• The script itself has no direct filesystem or shell access; the agents read, write, and run commands while the script coordinates them
• Up to 16 concurrent agents (fewer on machines with limited cores) and 1,000 agents total per run
• Runs are resumable within the same session, but exiting Claude Code and returning starts the workflow fresh

A note on cost

A workflow spawns many agents, so a single run can use meaningfully more tokens than working through the same task in conversation. Gauge the spend by running on a small slice first — one directory instead of the whole repo, or a narrow question instead of a broad one — and watch per-agent token usage in the /workflows view, stopping at any time without losing completed work. Check /model before a large run, and ask Claude to route stages that do not need the strongest model to a smaller one.

The takeaway

Dynamic workflows are not a fancier YAML pipeline and they are not just 'more subagents'. They are the orchestration itself, moved into a script Claude writes and you can rerun, with intermediate results kept out of the context window so the work can scale to hundreds of agents. Use subagents and skills for tasks one conversation can coordinate, and reach for a workflow when the plan is worth codifying — a repo-wide audit, a large migration, or research that has to be cross-checked. Start with /deep-research, then have Claude write one for a real task and save the run you like.