Claude Code Dynamic Workflows: Orchestrate Many Subagents

Subagents, skills, agent teams, and workflows can all run multi-step tasks. The difference is who holds the plan:

• With subagents and skills, Claude decides turn by turn what to spawn next, and every result lands in its context window. Good for a few delegated tasks per turn.
• With agent teams, a lead agent supervises a handful of long-running peer sessions through a shared task list.
• With a workflow, the script holds the loop, the branching, and the intermediate results in variables. Claude's context receives only the final answer. It scales to dozens or hundreds of agents per run, and a run can be resumed within the same session.

Putting the plan in code also lets a workflow apply a quality pattern, not just more agents: independent agents can adversarially review each other's findings before anything is reported, or a plan can be drafted from several angles and compared. Typical fits are codebase-wide audits, large migrations, research that needs sources cross-checked, and keep-fixing-until-the-check-passes loops.

The quickest way to see one is the bundled workflow:

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

It fans web searches out across several angles, fetches and cross-checks sources, votes on each claim, and returns a cited report with claims that did not survive cross-checking removed; claims the verifiers could not check are listed as unverified rather than refuted.

For your own task, ask in your own words or include the keyword ultracode:

1ultracode: audit every API endpoint under src/routes/ for missing auth checks2use a workflow to run npx tsc --noEmit and keep fixing the reported errors until3the type check passes or two rounds in a row make no progress

The keyword only starts a workflow from a prompt you type yourself; a prompt from -p, a scheduled task, or a relayed webhook or PR comment does not trigger it. To have Claude plan a workflow for every substantive task in a session, run /effort ultracode (or start with claude --effort ultracode). That uses noticeably more tokens per request, so turn it off with /effort ultracode off for routine work.

Runs execute in the background. /workflows opens the progress view: each phase with its agent counts, drill-down into each agent's prompt, tool calls, and result, and keys to pause (p), stop (x), restart an agent (r), or save the script (s).

Before a run starts, the CLI shows the planned phases with options to run it, run it and stop asking for that saved workflow in this project, view the raw script, or cancel. Ctrl+G opens the script in your editor. When you are prompted depends on the permission mode:

• Auto: first launch only; consent is recorded in your user settings. Skipped entirely with ultracode on.
• Manual, accept edits: every run, unless you chose "don't ask again" for that workflow.
• Bypass permissions: no prompt.
• claude -p and the Agent SDK: no prompt; the launch goes through normal permission evaluation, so you need an allow rule (Workflow for all, or Workflow(<name>) for one saved workflow), auto mode, bypass mode, a PreToolUse hook that returns allow, or a host approval callback.

The agents a workflow spawns get the same permission checks and sandboxing as any other tool call in the session; the script is coordination, not elevated access. To avoid a long run stalling on prompts, add the tools the agents need to your allow rules before starting. In auto mode, the prompt the script passes to agent() does not count as a request from you when the classifier reviews that subagent's actions, because Claude Code marks it as computed text.

A saved workflow is a .js file with a meta block and a plain JavaScript body using top-level await:

1export const meta = {2  name: 'audit-routes',3  description: 'Audit every route handler for missing auth checks',4}5 6const found = await agent('List every .ts file under src/routes/.', {7  schema: { type: 'object', required: ['files'],8            properties: { files: { type: 'array', items: { type: 'string' } } } },9})10 11const audits = await pipeline(found.files, file =>12  agent(`Audit ${file} for missing authentication checks.`, { label: file }),13)14 15return audits.filter(Boolean)

agent() spawns one subagent; with a schema, it returns JSON of that shape instead of prose (retried up to five times if validation fails). pipeline() runs one agent per item; parallel() runs a set of agent tasks at once. phase() groups agents under a title in the progress view, log() shows a message, and a saved workflow reads its input from the global args. An agent() call resolves to null if stopped or hit by an unrecoverable error, which is why the example filters the results.

To keep a run, open /workflows, select it, and press s. Save to .claude/workflows/ to share it with the repository, or ~/.claude/workflows/ for yourself; either way it runs as /<name>, for example Run /triage-issues on issues 1024, 1025, and 1030. Plugins can ship workflows too, namespaced as /plugin-name:workflow-name.

The script runs in an isolated environment with deterministic replay in mind: Date.now(), Math.random(), and argument-less new Date() throw inside it, so a relaunched run repeats the same agent() calls. Pass timestamps in through args instead.

That determinism is what makes runs resumable within the session. Pause and resume with p in /workflows; for a stopped run, ask Claude to relaunch it. On relaunch, completed agents return their saved results, but the first agent whose prompt differs (because you edited the script or an earlier result changed), any agent that failed, and every agent that started after either of those, run again. So a failure in the middle of a fan-out re-runs work that had finished after it.

Agents whose output stops arriving restart automatically from the same prompt, up to five times. If you hit your claude.ai usage limit, an interactive run pauses until the limit resets (when autoContinueAtUsageLimit is on and the reset is within 24 hours) rather than failing those agents.

A workflow spawns many agents, so one run can use far more tokens than working through the task in conversation, and it counts toward your plan's usage and rate limits like everything else.

The docs' advice: run on a small slice first, such as one directory instead of the whole repository or a narrow question instead of a broad one, and watch per-agent token use in /workflows. You can stop a run there at any time, usually without losing completed work. Claude Code flags a run with more than 25 agents, or a projected total over 1.5 million tokens, with a Large workflow warning in the task panel; the warning is advisory and does not pause the run.

Two settings shape cost directly. The size guideline in /config (small under 5 agents, medium under 10, large under 50, or unrestricted) tells Claude how many agents to aim for; it defaults to medium, or small on Pro. And models: workflow agents run on your session's model unless the script names one, so check /model before a large run and ask Claude to use a smaller model for stages that do not need the strongest.

Use a repository with a test or lint command.

1. Run /deep-research on a question about a library you use, and read how the report marks verified and unverified claims. 2. Ask: "use a workflow to audit every file under src/<one-directory>/ for <one specific issue>, and adversarially verify each finding before reporting it". 3. At the approval prompt, choose View raw script and read how many agents it will start. 4. Run it and open /workflows; drill into one agent to see its prompt and result. Note the token use. 5. Press s and save it to .claude/workflows/. 6. Run the saved /<name> on a second directory.

Pass criterion: the audit's findings were verified before reporting, you know what one run cost, and the saved command reran the same orchestration elsewhere.