Running Claude Code's Dynamic Workflows: What I Learned About Orchestrating Subagents

I use Claude Code as everyday infrastructure, and the first thing that felt genuinely new was Dynamic Workflows. The trigger was mundane: when I do background research for the four technical blogs I run, calling subagents by hand over and over got tedious. The feature, added in v2.1.154, freezes that "calling over and over" part into a JavaScript script.

I misread it at first. A Dynamic Workflow is not a way to "spawn more subagents." It moves the plan itself into code and lets the runtime hold the execution order and the intermediate results. Only the final answer comes back into your conversation context, so even a long investigation doesn't clutter your working context. Miss this point and you'll just burn tokens for nothing.

Where workflows sit next to subagents and skills

The official docs separate the three by "who holds the plan." Here's how I think about it.

• Subagents: Claude decides turn by turn what to spawn next. Intermediate results pile up in Claude's context.
• Skills: Claude follows a prompt (SKILL.md). The decision-maker is still Claude.
• Workflows: the script holds the loop, the branching, and the intermediate state. Claude writes the script and receives the final result.

The scale differs sharply too. Subagents handle a few delegated tasks per turn; a workflow can drive dozens to hundreds of agents in a single run (capped at 16 concurrent, 1,000 total). When a task outgrows what one conversation can coordinate, like a several-hundred-file migration or research that needs cross-checked sources, that's when I reach for a workflow.

Start by running /deep-research

Before writing my own script, running the built-in /deep-research was the fastest path to understanding. It runs a chain of phases in the background: decompose the question into angles, search in parallel, fetch sources and extract claims, verify them adversarially, then synthesize a cited report.

Enabling it is just flipping the "Dynamic workflows" row in /config. It's available on Pro and higher paid plans, with API access, and on the major clouds (Bedrock, Vertex AI, Foundry). Once ready, you hand it the question directly.

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

When you run it, Claude Code asks whether to allow the workflow, and spells out the warning that running many subagents in parallel uses a lot of tokens. I shrugged that off the first time, launched a big investigation on my usual small model, and was surprised how much it consumed. Check /model before you run.

In the confirmation dialog, "View raw script" lets you read the actual JavaScript that runs. Skimming it once gives you a blueprint for writing your own workflow later.

Follow progress with /workflows

Workflows run in the background, so the session stays responsive. To watch, run /workflows.

/workflows

Each phase appears with its agent count, cumulative tokens, and elapsed time. Arrow keys select a phase; Enter drills in so you can see which URL each agent hit and what it found. More than once, looking at the Search phase output made me realize my query angles were skewed, and I adjusted how I phrased the question.

Four keys are worth memorizing: p to pause and resume, x to stop an agent or the whole workflow, r to restart a stopped agent, and s to save the script. If you stop a run, the agents that already finished return cached results, so resuming continues from there, though resume only works within the same session; quit Claude Code and the next session starts fresh.

Turning your own task into a workflow

After the built-in one, your own task is next. There are two ways to have Claude write a workflow.

1. Include the word workflow in your prompt. The word gets highlighted in the input box, and Claude generates a workflow script instead of working turn by turn.
2. Enable /effort ultracode. Alongside xhigh-level reasoning, Claude plans a workflow for every substantive task in the session.

I usually use the first one, with workflow written explicitly. Ultracode can split a single request into several workflows ("understand, change, verify") and feels too heavy for routine work. If workflow gets highlighted by accident, alt+w ignores it for that turn.

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

Once you're happy with the run, you can save it for reuse. In /workflows, select the run and press s to choose where to save.

• .claude/workflows/ (project root): shared with everyone who clones the repo.
• ~/.claude/workflows/ (home): available in every project, visible only to you.

A saved workflow runs as /<name> and shows up in / autocomplete in later sessions. If a project version and a personal version share a name, the project one wins. Running the same orchestration every time for something like a per-branch review pays off more than I expected.

Constraints worth knowing before you run

Here are the limits I hit, or expect to hit, in real use.

• No user input mid-run. If you want sign-off between stages, split them into separate workflows.
• The script itself can't touch the filesystem or shell. Agents do the reading, writing, and command execution; the script only coordinates.
• 16 concurrent agents, 1,000 total per run. This bounds runaway loops.
• Every agent uses your session's model. For stages that don't need the strongest model, ask Claude to route them to a smaller one.

To disable, use the /config toggle, "disableWorkflows": true in ~/.claude/settings.json, or the CLAUDE_CODE_DISABLE_WORKFLOWS=1 environment variable. For a whole organization, set the same key in managed settings.

A first step to try

If you try one thing today, flip Dynamic workflows on in /config and hand /deep-research a question you're actually stuck on. Then read its phase structure once via "View raw script" so you can feel what's happening as a program.

As an indie developer running multiple sites alone, I have a hunch this "freeze the plan into code" idea is going to matter. I went deeper on writing your own scripts in Authoring Dynamic Workflows: building reusable research pipelines with phase / agent / pipeline. To keep the instructions you hand those scripts lightweight, keeping SKILL.md under 200 lines is a useful companion read.

Thank you for reading.