Dynamic Workflows in Claude Code: when Claude orchestrates its own agent swarm

Dynamic Workflows shipped with Claude Opus 4.8 on May 28, 2026, as a research preview in Claude Code. The idea: instead of you breaking a large job into pieces and dispatching them, Claude writes a structured multi-step plan itself and orchestrates the work across many subagents running in the background — tens, hundreds, up to roughly a thousand for the largest jobs.

This is aimed at work a single agent in a single context window cannot do well: migrating a pattern across hundreds of thousands of lines of code, auditing every file in a large repo, or running the same transform over a long list of items where doing them one at a time would take all day.

What it actually is

A workflow is a deterministic script that fans work out across subagents. Claude authors the script — what runs in parallel, what runs in sequence, what verifies the result — and then executes it. The building blocks are simple:

• Fan-out (parallel). Run many subagents at once — one per file, per module, per item — and collect their results.
• Pipeline. Push each item through several stages (find → fix → verify) independently, so one item can be in stage three while another is still in stage one.
• Phases. Group the work so you can see progress: "Scanning 340 files," then "Applying fixes," then "Verifying."

Each subagent gets its own context window, its own prompt, and its own slice of the job. The lead agent stitches the results back together. Because the plan is a script and not a freeform conversation, the same job runs the same way each time — that determinism is the point.

How it differs from what you already have

Claude Code now has several ways to run more than one agent, and they're easy to conflate:

Feature	Who plans the work	Best for
Sub-agents	You invoke one for a scoped task	Delegating a single side-quest (search, review)
Agent Teams	You define named roles up front	A fixed division of labor you reuse
claude agents	You launch parallel tasks by hand	Running several independent jobs at once in the terminal
Dynamic Workflows	Claude writes and runs the plan	One large job decomposed into many similar pieces

The distinction that matters: with Agent Teams and claude agents, you decide the structure. With Dynamic Workflows, Claude decides the structure — it looks at the job, writes the fan-out plan, and runs it. You approve the plan, not each step.

When it's worth it — and when it isn't

Worth it: the job is large, repetitive, and decomposable. "Rename this API across the whole monorepo." "Add the new license header to every source file." "Find every place we call the deprecated client and migrate it." These are tasks where the work is mostly the same shape repeated hundreds of times, and where parallelism turns hours into minutes.

Not worth it: the job is small, or it's a tightly-coupled change where every edit depends on the last. Spinning up a swarm to edit three files is slower and more expensive than just doing it. And a deeply sequential refactor — where step 5 can't be written until step 4 is reviewed — doesn't parallelize, so a workflow buys you nothing.

The cost model, stated plainly

Parallel agents mean parallel context windows. Ten subagents reading the codebase is roughly ten times the input tokens of one agent reading it once, and up to ~1,000 subagents is a real bill. Opus 4.8 also defaults to high effort, which raises per-call token use further. None of this is hidden — but it's easy to launch a workflow over a large repo and be surprised by the token count.

Two habits keep it sane:

1. Scope the input. Point the workflow at the directory or file set that actually needs the change, not the whole repo, so subagents aren't re-reading code that won't be touched.
2. Watch the run. Use /usage to see the token breakdown mid-session, and stop a workflow that's ballooning rather than letting it run to completion.

This is the same discipline that separates productive Claude Code use from the antipattern of letting context and cost run unchecked — just at a larger scale, because a workflow multiplies whatever a single agent would have spent.

Getting it

Dynamic Workflows arrived in the Claude Code v2.1.154 range alongside Opus 4.8 support. As a research preview, expect the surface to change. The official docs live at code.claude.com/docs.

Try this today

Pick a genuinely repetitive chore you've been avoiding — a mechanical rename, a header insertion, a deprecated-call migration — scoped to one directory. Ask Claude Code to plan a workflow for it, read the plan before approving, and run it on that one directory. You'll learn more about where workflows help (and where they overspend) from one real scoped run than from any amount of reading.