Claude Code · Operator Reference

Running Workflows

How to trigger, watch, approve, save, and control dynamic workflows from the Claude Code CLI — the operator layer. For writing workflow scripts (agent(), pipeline(), quality patterns), see Part 1 · Writing the Script.

research preview v2.1.154+ CLI · Desktop · IDE all paid plans

01 What Dynamic Workflows Are

A dynamic workflow is a JavaScript script that orchestrates subagents at scale. Claude writes the script for the task you describe; a runtime executes it in the background while your session stays responsive. Agents address the problem from independent angles, other agents try to refute what they found, and the run iterates until answers converge — producing results a single pass cannot.

What workflows are for

Problems too big for one pass: a bug hunt across an entire service, a migration touching hundreds of files, a plan worth stress-testing from every angle before you commit. Progress is saved as the run goes — an interrupted job picks up where it left off instead of starting over.

Availability

Surface	Status
Max, Team plans	On by default
Enterprise plan	Off by default at launch. Admin enables in Claude Code admin settings.
Pro plan	Toggle Dynamic workflows on in `/config`.
Anthropic API	On by default
Amazon Bedrock, Google Cloud Vertex AI, Microsoft Foundry	On by default
Minimum version	Claude Code v2.1.154 or later

Token cost warning

A workflow spawns many agents. A single run can use meaningfully more tokens than working through the same task in conversation. Start on a scoped task — one directory, not the whole repo — to gauge usage before committing to a large run.

02 The Four Primitives — When to Use a Workflow

Subagents, skills, agent teams, and workflows can all run multi-step tasks. The difference is who holds the plan. A workflow moves the plan into code — the script holds the loop, the branching, and intermediate results itself, so Claude's context holds only the final answer.

	Subagents	Skills	Agent teams	Workflows
What it is	A worker Claude spawns	Instructions Claude follows	A lead agent supervising peer sessions	A script the runtime executes
Who decides what runs next	Claude, turn by turn	Claude, following the prompt	The lead agent, turn by turn	The script
Where intermediate results live	Claude's context window	Claude's context window	A shared task list	Script variables
What's repeatable	The worker definition	The instructions	The team definition	The orchestration itself
Scale	A few delegated tasks per turn	Same as subagents	A handful of long-running peers	Dozens to hundreds of agents per run
Interruption	Restarts the turn	Restarts the turn	Teammates keep running	Resumable in the same session

Also: codified quality patterns

Moving the plan into code lets a workflow apply a repeatable quality pattern — not just run more agents. Independent agents adversarially reviewing each other's findings, or drafting a plan from several angles and weighing them, produce more trustworthy results than any single pass. For the scripting patterns themselves, see Part 1 · Writing the Script.

03 Triggering a Workflow

Per-task: the ultracode keyword

Include ultracode in your prompt, or ask in plain language ("use a workflow", "run a workflow"). Claude Code highlights the keyword and Claude writes a workflow script for the task instead of working turn by turn.

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

# Or in plain language — both work:
Use a workflow to audit every API endpoint under src/routes/ for missing auth checks

Dismissing the trigger

If you typed ultracode without meaning to trigger a workflow: press Option+W (macOS) or Alt+W (Windows / Linux) to dismiss for this prompt, or press Backspace while the cursor is right after the highlighted keyword. To disable the trigger entirely, turn off Ultracode keyword trigger in /config.

Before v2.1.160 the trigger keyword was workflow (not ultracode). Natural-language requests ("use a workflow") work in both versions.

Session-wide: /effort ultracode

/effort ultracode combines xhigh reasoning effort with automatic workflow orchestration for the session. With it on, Claude plans a workflow for each substantive task — you don't ask per task.

/effort ultracode

One request can become several workflows in sequence — understand → change → verify.
Every task uses more tokens and takes longer than at lower effort levels.
Lasts for the current session only; resets when you start a new one.
Drop back to /effort high for routine work.
Available only on models that support xhigh effort; others omit it from the /effort menu.

Running a named workflow directly

Bundled workflows and any workflow you've saved run as /<name> commands and appear in / autocomplete. Run them directly — no trigger keyword needed.

04 Approving the Run

The per-run prompt (CLI)

The first time a workflow triggers (per-mode rules below), Claude Code shows the planned phases and asks before anything runs:

Yes, run it — start the run.
Yes, and don't ask again for <name> in <path> — start, and skip this prompt for this workflow in this project from now on.
View raw script — read the full JS before deciding. Ctrl+G also opens it in your editor.
No — cancel.

Tab lets you adjust the prompt before the run starts.

When you're prompted — by permission mode

Permission mode	When prompted
Default, accept edits	Every run, unless you've selected Yes, and don't ask again for that workflow in this project.
Auto	First launch only. Any "Yes" records consent in your user settings; later launches start without prompting. Skipped entirely when ultracode is on.
Bypass permissions, `claude -p`, Agent SDK	Never. The run starts immediately.

Desktop app

An approval card shows the workflow name, the phase list, and a token-usage caution — with Once, Always, and Deny actions. The progress view appears in the Background tasks side pane.

05 Subagent Permissions During a Run

Your permission mode controls only the launch prompt above. Once a run is in progress, spawned agents follow their own rules — independent of your session's mode.

Subagents always run in acceptEdits mode and inherit your tool allowlist, regardless of your session's permission mode.
File edits are auto-approved — subagents can read and write files without prompting you.
Shell commands, web fetches, and MCP tools not in your allowlist can still prompt you mid-run.
In claude -p and the Agent SDK there is no one to prompt — tool calls follow your configured permission rules without interactive confirmation.

Pre-allow before a long run

A mid-run permission prompt pauses the workflow and waits for you. On a long job this is disruptive. Before starting, add the shell commands, web fetches, or MCP tools the agents will need to your allowlist. Run /fewer-permission-prompts to auto-generate an allowlist from recent transcript history.

06 The /workflows Live Monitor

Workflows run in the background — your session stays responsive. Run /workflows at any time to list running and completed workflows, then select one to open its progress view.

/workflows

The progress view shows each phase with agent counts, token totals, and elapsed time.

Key	Action
`↑` / `↓`	Select a phase or agent
`Enter` or `→`	Drill into the selected phase, then into an agent to read its prompt, recent tool calls, and result
`Esc`	Back out one level
`j` / `k`	Scroll within the agent detail when it overflows
`p`	Pause or resume the run
`x`	Stop the selected agent, or stop the whole workflow when focus is on the run
`r`	Restart the selected running agent
`s`	Save the run's script as a reusable command (see §08)

Progress also inline

A collapsible progress line appears in the task panel below the input box while a run is active. Expand it without opening the full /workflows view.

07 Bundled: /deep-research

Claude Code ships one bundled workflow out of the box:

Command	What it does
`/deep-research <question>`	Fans out web searches across several angles, fetches and cross-checks the sources it finds, votes on each claim, and returns a cited report — with claims that didn't survive cross-checking filtered out. Requires the WebSearch tool to be available.

Workflows you save yourself (§08) appear in / autocomplete alongside bundled ones — same invocation pattern.

Quickest way to see a workflow in action

Run /deep-research on a question. Agents work through phases in the background, your session stays free, and you get one report at the end instead of a turn-by-turn transcript.

08 Saving for Reuse

How to save a run as a command

Open /workflows

Select the completed run you want to keep.

Press s

The save dialog opens. Tab toggles between two save locations.

Choose a location and press Enter

The workflow now runs as /<name> in future sessions.

Save locations

Location	Scope	Path
Project	Shared with everyone who clones the repo	`.claude/workflows/`
Personal	Available in every project, visible only to you	`~/.claude/workflows/`

If a project workflow and a personal workflow share a name, the project one runs.

Passing input at invocation time

A saved workflow can accept input through the args parameter — the script reads it as a global named args. Invoke it in natural language and Claude passes structured data; the script can call array and object methods on args directly without parsing.

# Claude infers the args from your natural-language request:
Run /triage-issues on issues 1024, 1025, and 1030

If args is omitted at invocation time, the global is undefined inside the script.

Pass args as structured data, not JSON strings

When invoking programmatically: pass args: ["a.ts", "b.ts"] (an actual array), not args: '["a.ts", ...]' (a JSON-encoded string). A stringified list breaks args.filter() and args.map() inside the script.

09 How Runs Work & Managing Runs

Execution model

The runtime executes the script in an isolated environment, separate from your conversation. Intermediate results stay in script variables — not in Claude's context window. Claude's context holds only the final answer.

Every run auto-writes its script to a file under ~/.claude/projects/. Claude receives the path when the run starts — ask for it to inspect, diff, or edit the script.
The runtime tracks each agent's result as the run progresses. This is what makes runs resumable.

Resuming a paused or stopped run

Open /workflows, select the run, and press p to resume. Or ask Claude to relaunch with the same script. Agents that already completed return their cached results instantly; the rest run live.

Same-session only

Resume works within the same Claude Code session. If you exit Claude Code while a workflow is running, the next session starts the workflow fresh — cached results from the prior session are not available.

Hard limits

min(16, cpu−2)

Max concurrent agents

1,000

Max agents per run

same-session

Resume window

Constraint	Why
No mid-run user input	Only agent permission prompts can pause a run. For sign-off between stages, run each stage as its own workflow.
No direct filesystem or shell access from the workflow script	Agents read, write, and run commands. The script coordinates the agents — it doesn't access files or shell directly.
≤16 concurrent agents (fewer on limited CPU)	Bounds local resource use. Excess `agent()` calls queue and run as slots free — all items complete, just not all simultaneously.
1,000 agents total per run	Hard backstop against runaway loops. Well above the ceiling of any real workflow.

10 Cost

Workflows spawn many agents — a single run can use meaningfully more tokens than working through the same task in conversation. Runs count toward your plan's usage and rate limits like any other session.

Before a large run

Scope it first. Run the workflow on a small slice — one directory instead of the whole repo, or a narrow question before a broad one. Gauge the spend before committing.
Check your model. Run /model before a large run if you usually switch to a smaller model for routine work. Every agent uses your session's model unless the script routes a stage to a different one.
Ask for cheaper stages. When describing the task, ask Claude to use a smaller model for stages that don't need the strongest one.

During a run

The /workflows view shows each agent's token usage as the run progresses.
Stop at any time (x key) without losing completed work — agents that finished return cached results on resume.
The runtime's 1,000-agent cap bounds worst-case cost from a runaway script.

11 Turning Workflows Off

For yourself

Toggle Dynamic workflows off in /config. Persists across sessions.
Set "disableWorkflows": true in ~/.claude/settings.json. Persists across sessions.
Set CLAUDE_CODE_DISABLE_WORKFLOWS=1 as an environment variable. Read at startup — applies wherever you set it.

For your organisation

Set "disableWorkflows": true in managed settings.
Or use the toggle on the Claude Code admin settings page.

What disabling does

Bundled workflow commands (including /deep-research) become unavailable.
The ultracode keyword no longer triggers a run.
ultracode is removed from the /effort menu.