إنتقل إلى المحتوى الرئيسي

Dynamic Workflows & ultracode

متقدّم

A dynamic workflow is a JavaScript script that orchestrates subagents at scale. You describe a task; Claude writes the script; a runtime executes it in the background while your session stays responsive. Where a normal multi-step task lives turn-by-turn in Claude's context window, a workflow moves the plan into code — the loop, the branching, and every intermediate result live in script variables, so your context holds only the final answer.

That single shift is what makes workflows scale to dozens or hundreds of agents in one run, where ordinary delegation tops out at a handful.

When to reach for a workflow​

Claude Code gives you four ways to run multi-step work. The real question is who holds the plan:

SubagentsSkillsAgent teamsWorkflows
What it isA worker Claude spawnsInstructions Claude followsA lead supervising peer sessionsA script the runtime executes
Who decides what runs nextClaude, turn by turnClaude, per the promptThe lead, turn by turnThe script
Where results liveContext windowContext windowA shared task listScript variables
ScaleA few per turnSame as subagentsA handful of peersDozens to hundreds
On interruptionRestarts the turnRestarts the turnTeammates keep runningResumable in-session

Use 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. Canonical cases:

  • A codebase-wide bug sweep — fan a finder across every module, then have independent agents adversarially verify each finding before it's reported.
  • A 500-file migration — one agent per file, each in its own worktree, with a verification stage.
  • A research question where sources must be cross-checked against each other, not just summarized.
  • A hard plan worth drafting from several independent angles, then weighed against each other before you commit.

That last point is the underrated one: a workflow can apply a repeatable quality pattern (adversarial review, multi-angle drafting, majority-vote verification), so you get a more trustworthy result than a single pass — not just more agents.

The fastest way to see one: /deep-research​

Claude Code ships a built-in workflow so you don't have to write one to try the model. Run it on any question:

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

It fans web searches across several angles, fetches and cross-checks the sources, votes on each claim, and returns a cited report with claims that didn't survive cross-checking filtered out. Approve when prompted, then watch it work with /workflows. (It needs the WebSearch tool available.)

Three ways to start your own​

1. Ask in one prompt. Include the keyword ultracode, or just ask in plain words ("use a workflow", "run a workflow"). Claude writes a script for that single task without changing your session's effort level:

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

The keyword is highlighted in your input. Didn't mean it? Press Option+W (macOS) or Alt+W (Windows/Linux) to dismiss the highlight for that prompt.

:::note Keyword history Before v2.1.160 the literal trigger word was workflow; it was renamed to ultracode so the common word "workflow" wouldn't fire a run. Natural-language requests ("run a workflow") work in both versions. :::

2. Let Claude decide — ultracode effort. Set the session to ultracode and Claude plans a workflow for every substantive task, deciding on its own when one is warranted:

/effort ultracode

Ultracode combines xhigh reasoning effort with automatic orchestration. A single request can become several workflows in a row — one to understand the code, one to make the change, one to verify it. Every task then uses more tokens and takes longer, so drop back with /effort high for routine work. It lasts only the current session.

3. Run a saved or bundled command. /deep-research, or any workflow you've saved (below), appears in / autocomplete like any slash command.

Approve before it runs​

Workflows can spawn a lot of agents, so the CLI shows you the planned phases and asks first:

  • Yes, run it — start the run
  • Yes, and don't ask again for [name] in [path] — start and skip the prompt for this workflow in this project
  • View raw script (Ctrl+G opens it in your editor) — read before deciding
  • No — cancel (Tab lets you tweak the prompt first)

Whether you're prompted depends on your permission mode: Default / accept-edits prompts every run (unless you opted out for that workflow); Auto prompts on first launch only; bypass / claude -p / Agent SDK never prompt — the run starts immediately.

:::warning The subagents don't inherit your session's mode Whatever your session's permission mode, the agents a workflow spawns always run in acceptEdits and inherit your tool allowlist — file edits are auto-approved. Shell commands, web fetches, and MCP tools not on your allowlist can still pause the run to prompt you. On a long unattended run, add the commands the agents need to your allowlist before starting so it doesn't stall waiting on you. See Hardening Autonomous Runs. :::

How a run executes​

The runtime runs the script in an isolated environment, separate from your conversation — intermediate results stay in script variables, never touching Claude's context. The script itself has no direct filesystem or shell access: the agents read, write, and run commands; the script only coordinates them.

Every run writes its script to a file under your session directory in ~/.claude/projects/, and Claude gets the path. So you can ask Claude for the script, read the orchestration it wrote, diff it against a previous run, or edit it and ask Claude to relaunch from your edited version.

The runtime enforces a few caps so a bad script can't run away:

ConstraintWhy
No mid-run user input (only agent permission prompts pause it)For sign-off between stages, run each stage as its own workflow
Script has no direct filesystem/shell accessAgents do the work; the script coordinates
Up to 16 concurrent agents (fewer on low-core machines)Bounds local resource use
1,000 agents total per runPrevents runaway loops

Watch and manage runs​

Run /workflows to list running and completed runs, then select one to open its progress view — each phase with its agent count, token total, and elapsed time. Drill into a phase, then an agent, to read its prompt, recent tool calls, and result. Key controls:

KeyAction
↑ / ↓Select a phase or agent
Enter / →Drill in; Esc backs out
fFilter agents by status (v2.1.186+)
pPause or resume the run
xStop the selected agent — or the whole run when focus is on it
rRestart the selected running agent
sSave this run's script as a command

A one-line progress summary also appears in the task panel below your input box; press down-arrow to focus it, Enter to expand.

Resume: stop a run and resume it later (p) — agents that already finished return cached results, the rest run live. Resume works within the same session; exit Claude Code mid-run and the next session starts it fresh.

Save a workflow for reuse​

When Claude writes a good orchestration for something you'll repeat — a review you run on every branch — press s in /workflows to save that run's script. Tab toggles where:

  • .claude/workflows/ in your project — shared with everyone who clones the repo
  • ~/.claude/workflows/ in your home — available everywhere, only you see it

It then runs as /[name] in future sessions. A saved workflow can take input via an args global, so you parameterize it at call time instead of editing the script:

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

Claude passes the list as structured data, so the script calls array/object methods on args directly.

Mind the cost​

A workflow spawns many agents, so one run can use meaningfully more tokens than doing the same task in conversation, and it counts toward your plan's usage and rate limits. Two habits keep this sane:

  • Slice first. Run on one directory (not the whole repo) or a narrow question first to gauge spend; /workflows shows per-agent token usage live, and you can stop anytime without losing completed work.
  • Right-size the model. Every agent uses your session's model unless the script routes a stage elsewhere. Check /model before a large run, and when you describe the task, ask Claude to use a smaller model for stages that don't need the strongest one. See Cost & Latency and Choosing a Model.

Common mistakes​

  • Expecting a human-in-the-loop mid-run. There's no mid-run input. If a task needs your sign-off between stages, split it into separate workflows.
  • Forgetting the allowlist on unattended runs. A long workflow stalls the moment an agent hits a non-allowlisted shell command. Pre-authorize what the agents need.
  • Reaching for a workflow when a subagent would do. A few delegated tasks per turn is what subagents are for. Workflows earn their overhead at fleet scale or when you want the orchestration saved as a rerunnable script.
  • Running ultracode effort all session for routine edits. It plans a workflow for everything — great for hard work, wasteful for a one-line fix. Drop to /effort high.

Turn workflows off​

Toggle Dynamic workflows off in /config, set "disableWorkflows": true in ~/.claude/settings.json, or set the CLAUDE_CODE_DISABLE_WORKFLOWS=1 environment variable. Organizations can disable them in managed settings. When off, bundled workflow commands disappear and ultracode no longer triggers a run or appears in the /effort menu.

Next​