Dynamic workflows and ultracode

A Claude Code dynamic workflow is a JavaScript script Claude writes for a task, which a background runtime executes to orchestrate dozens to hundreds of subagents per run, keeping intermediate results out of Claude’s context. The keyword ultracode starts one for a single prompt; /effort ultracode has Claude plan one for every substantive task.

This page is for developers who run large, repetitive jobs through Claude Code, and for tech leads who want those jobs saved as shared, reviewable commands. The situation it solves: you asked Claude to audit 140 route handlers, it delegated to a few subagents, the context filled with half-read findings, and the answer you got back covers a third of the routes with no way to tell which third.

What you get from a dynamic workflow setup

• A test for when a workflow beats subagents, /goal or a plain session.
• Six copy-paste prompts with a verification phase built in.
• A saved workflow command in .claude/workflows/ your team reruns on every branch.
• A routine that proves the output without reading every file the agents touched.
• Recovery steps for stalled permission prompts, partial reruns, usage limits and cost overruns.

Dynamic workflows arrived in Claude Code v2.1.154 (2026-05-28). Everything on this page was checked on 2026-09-26 against v2.1.283 (the latest channel) and the official workflows reference, except the passages that name 2026-10-12, a version after v2.1.283, Sonnet 5.5 or Haiku 5.5, which were re-checked against Claude Code 2.1.296 and Anthropic’s pages on 2026-10-12. Every workflow feature used here, and Opus 5.5 as the default model (v2.1.280), is on both release channels: stable is v2.1.287 on 2026-10-12.

When does a workflow beat subagents or /goal?

A dynamic workflow is one kind of agentic workflow: the task runs in several passes, through subagents, instead of one answer. The difference between the four ways to run a multi-step task is who holds the plan:

	Subagents	Skills	Agent teams	Workflows
Who decides what runs next	Claude, turn by turn	Claude, following the prompt	A 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

Use this decision rule:

• The same step runs over many items (every route, every component, every changed file): use a workflow.
• The result must be cross-checked before you trust it (security findings, research claims): use a workflow, because the script can make independent agents refute each other’s findings every time, not only when Claude remembers to.
• The end state is one pass/fail condition (“the build is green”): use /goal. It is cheaper and needs no script.
• You need two or three lookups this turn: use subagents.
• You want several long-lived sessions you steer yourself: use agent view.

For the patterns behind these choices (fan-out/fan-in, best-of-N with a judge, writer/reviewer separation) and how they map to Codex and Cursor, see multi-agent orchestration patterns. For a side-by-side of parallel options inside one repo, see multi-file workflows.

Start your first workflow

1. Check that workflows are on. They are on by default on every plan except Pro. On Pro they are off until you turn on the Dynamic workflows row in /config, which writes enableWorkflows to your user settings. They also run on Amazon Bedrock, Google Cloud’s Agent Platform (formerly Vertex AI) and Microsoft Foundry.

2. Pre-approve the tools the agents need. Workflow subagents use your permission rules, and in Manual mode each one that hits an unapproved tool pauses the run for a prompt. Before a long run, add the test, lint and read commands to permissions.allow in .claude/settings.json. See permissions and sandboxing for a safe baseline.

3. Try a small slice first. Point the prompt at one directory, read the report, then widen it. The /workflows view shows token use per agent, so the slice tells you what the full run will cost.

4. Ask for the workflow. Put the keyword ultracode in your prompt, or ask in your own words (“use a workflow”). Claude writes the script instead of working turn by turn.

5. Approve the plan. In Manual and accept-edits modes, Claude Code shows the planned phases with Yes, run it, View raw script and No (a saved or bundled workflow adds Yes, and don’t ask again for that workflow in this project). Choose View raw script the first time: the phases tell you whether a verification step exists before any tokens are spent. Ctrl+G opens the script in your editor; Tab lets you adjust the prompt. In auto mode you approve only the first launch; in bypass-permissions mode nothing asks.

6. Watch the run. Run /workflows, select the run and press Enter. Each phase shows its agent count, token total and elapsed time.

Copy-paste prompt: auth audit with adversarial verification

ultracode: audit every route handler under src/routes/ for missing authentication or authorization checks. One agent per file. For each finding, record the file, line, the missing check and the request that would exploit it. Then run a second phase in which a different agent tries to refute each finding by reading the middleware chain in src/middleware/ and the router setup; keep only findings that survive. Return a table sorted by severity, plus a list of files that no agent could finish.

The last sentence matters. A report that lists what failed to run is the difference between “no findings” and “no findings in the 60% that ran”.

Watch and steer a run in /workflows

Key	Action
↑ / ↓	Select a phase or agent
Enter or →	Drill into a phase, then into an agent’s prompt, tool calls and result
Esc or ←	Back out one level
f	Filter the agents in a phase by status; press again to cycle
p	Pause or resume the run
x	Stop the selected agent, or the whole run when focus is on the run
r	Restart the selected running agent
s	Save the run’s script as a command

A one-line progress row also sits in the task panel below the input box. Press the down arrow to focus it, then Enter to expand it.

Which workflow prompts work well?

A workflow fits a task larger than one agent can hold, or one step repeated across many items. Each prompt below names its stop condition and its verification step. Without both, a workflow runs until the agent cap and verifies nothing.

Copy-paste prompt: JavaScript-to-TypeScript migration with a type gate

use a workflow to migrate every component under src/components/ from JavaScript to TypeScript. Work on each file in its own isolated copy so edits don't conflict. After each file, run npx tsc --noEmit on that file's copy and keep the change only if it type-checks without adding any `any` or `@ts-ignore`. Use a smaller model for the per-file conversions and the session model for the final merge. Finish by running npm test once on the merged result and report: files migrated, files skipped with the reason, and the test summary.

Copy-paste prompt: fix until the type check passes

use a workflow to run npx tsc --noEmit and keep fixing the reported errors until the type check passes or two rounds in a row make no progress. Group errors by file and give each file to its own agent. Do not change any file under src/generated/ and do not loosen tsconfig.json. At the end, report the error count per round and any errors left.

Copy-paste prompt: per-file PR review merged into one ranked summary

use a workflow to review every file changed on this branch against origin/main for correctness bugs: wrong conditions, missing error handling, broken invariants, unsafe concurrency. One reviewer per file. Then have one agent deduplicate the findings, drop anything it cannot point to a specific line for, and rank the rest by user impact. Output a markdown list with file:line, the bug, and a one-line reproduction.

Copy-paste prompt: find flaky tests until the list stops growing

use a workflow to find flaky tests in this repo: run the test suite repeatedly in parallel batches, record which tests fail intermittently with their error messages, and stop once two rounds in a row find nothing new. Do not edit any test. Report each flaky test with its failure rate across all runs and the most likely cause.

For research questions, the bundled /deep-research workflow is ready to use. It fans web searches out over several angles, cross-checks sources, votes on each claim, and returns a cited report with refuted claims filtered out. Claims the verifiers could not check (after a rate limit, say) are listed as unverified, not dropped. It needs the WebSearch tool:

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

An interactive terminal session allows 200 WebSearch calls, and searches from the main conversation and from every agent count against that one limit, so a wide research fan-out can reach it. From v2.1.290 (latest channel only on 2026-10-12) the limit refills at about 100 calls an hour, and CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR changes the rate; in a non-interactive session the refill default is 0, which turns it off. CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION raises the cap, and /clear resets the count (Claude Code tools reference and environment variables pages, checked 2026-10-12).

How do you verify a workflow’s output without reading every file?

A workflow can touch 500 files, so build the proof into the run and check the proof instead of each diff:

1. Put a deterministic gate in the prompt. “Keep the change only if tsc passes” or “run npm test once on the merged result” turns each agent’s claim into a check the machine ran. The migration and type-check prompts above do this. Your test suite is only as good as its assertions; see how strong is your test oracle.
2. Require an adversarial phase for findings. Audits and reviews should end with agents that try to refute each finding. The report then carries only findings that survived, and you spot-check two or three of them instead of all of them.
3. Require a “not done” list. Every prompt above asks for skipped or unfinished items. agent() returns null when an agent is stopped or hits an unrecoverable API error, so a script that silently filters nulls can report success on partial coverage.
4. Check the numbers against the repo. Compare “files migrated plus files skipped” with git ls-files src/components | wc -l in your terminal. A mismatch means the discovery phase missed files.
5. Run the full gate yourself once. After the run, run your normal type check, lint and test suite, then open the pull request. CI and review agents check it again, the same as any other change. Package the results as an evidence bundle so the reviewer signs off on evidence, not on a diff read line by line.

Who signs off: the developer who launched the run owns the pull request. For saved team workflows, the tech lead reviews the script in .claude/workflows/ like any other code, because every future run repeats its logic.

Let Claude decide with ultracode

ultracode is a Claude Code setting, not a model effort level. It leaves the session’s effort level unchanged (since v2.1.284; before that it set xhigh) and has Claude plan a workflow for each substantive task without being asked. claude --effort ultracode and the Agent SDK value effortLevel: "ultracode" also set the level to xhigh. Choosing another level in /effort no longer turns ultracode off: turn it off with /effort or the ultracode setting. One request can become several workflows in a row: one to understand the code, one to change it, one to verify it.

/effort ultracode

Other ways to turn it on: launch with claude --effort ultracode (v2.1.203 or later), move the effort slider in the /model picker to ultracode, or set "ultracode": true in a settings file to start every session with it.

Ultracode is available only when both of these hold:

• Dynamic workflows are turned on for you.
• The model supports xhigh. On 2026-10-12 that is Claude Opus 5.5, Sonnet 5.5, Haiku 5.5, Opus 5, Sonnet 5, Fable 5.1, Fable 5, Opus 4.8 and Opus 4.7. It is not on Opus 4.6 or Sonnet 4.6, and Haiku 4.5 has no effort setting.

An effort cap does not make ultracode unavailable: since v2.1.284 it stays on at the capped level.

Ultracode spends more on every request

Ultracode applies to every task in the session, so a substantive request can become one or more workflows that run many agents, and it uses more tokens and takes longer than the same request in an ordinary turn at the same effort level. On a subscription plan a session reaches its session or weekly limit sooner. Ultracode also switches off three guards: the Large workflow warning, the session’s concurrent subagent limit, and (in auto mode) the first-launch approval. Turn ultracode off in /effort when you go back to routine work. From v2.1.280 Claude Code’s default model is Opus 5.5, which runs at medium effort by default; see the models hub for defaults per provider.

Neither the persisted effortLevel setting nor CLAUDE_CODE_EFFORT_LEVEL accepts ultracode. If CLAUDE_CODE_EFFORT_LEVEL or an effort cap sets the session’s level, ultracode stays on at that level (v2.1.284 or later).

Save a workflow your team reruns

When a run does what you wanted, save its script as a command:

1. Run /workflows, select the run and press s.
2. Press Tab to choose the location:
   • .claude/workflows/ in the project, shared with everyone who clones the repo. Commit it and review it like code.
   • ~/.claude/workflows/, available in all your projects and visible only to you.
3. Press Enter. The workflow now runs as /<name> and appears in / autocomplete.

If a project workflow and a personal workflow share a name, the project one runs. In a monorepo, saving writes to the closest existing .claude/workflows/ between your working directory and the repository root. To share a workflow across repositories, ship it in a plugin’s workflows/ directory; it then runs as /<plugin>:<name>.

A saved workflow can take input. Say “Run /triage-issues on issues 1024, 1025, and 1030” and Claude passes the list to the script as the args global, already structured.

The saved file looks like this; recognize it when you review it:

export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)

agent() spawns one subagent, pipeline() runs one per item, parallel() runs a set at once, and phase() groups agents under a title in the progress view. A schema makes the agent return validated JSON instead of prose. In review, check two things: that a verification phase exists, and that .filter(Boolean) is paired with a count of dropped items, not used to hide them.

Copy-paste prompt: add a verification phase to a saved workflow

Run /workflow-authoring first so Claude loads the script reference, then send:

Edit .claude/workflows/audit-routes.js: after the audit pipeline, add a phase titled "Verify" in which a separate agent per finding tries to refute it by reading src/middleware/. Return only surviving findings, plus a count of files whose audit agent returned null. Keep the meta block a plain object literal.

/workflow-authoring (v2.1.248 or later) loads the script-writing reference Claude works from. After editing, run /reload-skills, then /<name> again.

Run a saved workflow headless in CI

The ultracode keyword does not start a workflow when the prompt arrives through claude -p, an Agent SDK message not marked as human input, a scheduled task, or a relayed webhook or pull request comment. Text you did not type cannot opt you into a large run. In headless runs, invoke a saved workflow by name and allow it explicitly:

claude -p "Run /audit-routes" --allowedTools "Workflow(audit-routes)" "Read" "Grep" "Glob"

Workflow(<name>) approves that one saved workflow; a bare Workflow rule approves all of them. Keep the rest of the allowlist read-only for audit jobs. In CI, run this only on trusted refs, never with secrets in the environment on a job that checks out contributor code; see automation and headless runs for the safe job layout.

Limits that shape how you write the prompt

Limit	What it means for your prompt
No user input mid-run	For sign-off between stages, run each stage as its own workflow.
The script has no filesystem, shell or import()	Agents read, write and run commands; the script only coordinates. Put library work inside an agent’s task.
Up to 16 concurrent agents by default, fewer on machines or containers with fewer CPUs	Raise it with CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS (1 to 256, v2.1.269 or later) only for inference-bound fan-outs.
Up to 4,096 items in one pipeline() or parallel() call; 1,000 agents per run	Split bigger jobs into batches by directory.
Date.now(), Math.random() and no-argument new Date() throw in the script	Pass a timestamp through args. This is what lets a relaunched run replay the same agent() calls.
Size guideline: small under 5 agents, medium under 10, large under 50, or unrestricted	The default is medium (small on Pro from v2.1.271). It is advice to Claude, not a cap. Set it with /config workflowSizeGuideline=small or the workflowSizeGuideline key.

Each agent runs on the model the script names for its stage, or your session model when none is named. Ask for a smaller model on mechanical stages in the prompt, as the migration prompt does. If your organization’s availableModels allowlist blocks the requested model, the agent runs on a substitute and /workflows shows a warning naming both. To run every workflow agent on one model while your other subagents keep theirs, set CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL (v2.1.296, latest channel only on 2026-10-12; Anthropic’s changelog entry says no more than that).

When a run schedules more than 25 agents or projects more than 1.5 million tokens, the progress row shows a Large workflow warning. It is advisory; stop the run from /workflows if the numbers surprise you. If you choose a size guideline yourself, its agent count replaces the 25-agent threshold.

Agents in one run share a prompt cache when they use the same model, effort, tools, output schema and working directory, so a uniform fan-out is cheaper than a varied one. Their cache lives five minutes by default; for a run whose stages sit idle longer than that, set subagentPromptCacheTtl to 1h (1-hour cache writes bill at a higher rate). For budgets across a team, see cost control.

What breaks when you run dynamic workflows?

The run sits still for minutes. An agent is waiting on a permission prompt, which is the only thing besides a usage-limit wait that pauses a run on its own. Answer the prompt, then add that tool to permissions.allow before the next run.

One agent failed and the relaunch reran half the job. On relaunch, completed agents return saved results only up to the first agent that failed or whose prompt changed; everything that started after it runs again. If A, B, C and D started in order and B failed, A returns from cache and B, C and D run again. Stopping a single agent with x counts as a failure. Recovery: stop the whole run instead of single agents when you intend to relaunch, and split expensive stages into separate workflows.

The run is gone after you came back. Resume works within the same session. If you exited with Exit and stop tasks, claude --resume into that session and ask Claude to relaunch; completed agents return their saved results. A fresh session has no earlier run and starts over. If Claude Code cannot find the saved results at all, the relaunch fails with nothing to resume; ask Claude to start the workflow over as a new run. Next time, with agent view on, choose Move to background and exit to keep the run going.

Agents fail at your usage limit. From v2.1.271 an interactive run signed in with a claude.ai subscription pauses and resumes after the reset, provided autoContinueAtUsageLimit is on, the reset is within 24 hours and the run has not already waited twice. Under claude -p, the Agent SDK or a background session, the agents fail instead. Size headless runs with workflowSizeGuideline and a narrow slice.

The word “ultracode” in your prompt started a run you didn’t want. Press Option+W on macOS or Alt+W on Windows and Linux to dismiss the highlight for that prompt. To stop the keyword triggering at all, turn off Ultracode keyword trigger in /config, or set "workflowKeywordTriggerEnabled": false in a settings file.

Ultracode is missing from /effort. Your model lacks xhigh or workflows are off. Switch to an xhigh-capable model with /model (Opus 5.5 is the default from v2.1.280 on both release channels), or ask your admin whether workflows are turned off.

The report is confident but thin. Nulls were filtered or discovery missed files; apply steps 3 and 4 of the verification section.

In auto mode, the classifier blocks an agent action you expected to pass. Claude Code marks the prompt a script passes to agent() as script-computed text, so the classifier does not treat it as your request. Pre-approve the commands the agents need in permissions.allow, or run the stage in Manual mode with those rules in place.

Parallel edits collided. Agents wrote to the same files. Ask for “each file in its own isolated copy”, as the migration prompt does, and merge in a final phase.

Turn workflows off for yourself or your organization

• For yourself: toggle Dynamic workflows off in /config, set "disableWorkflows": true in ~/.claude/settings.json, or set CLAUDE_CODE_DISABLE_WORKFLOWS=1 in the environment you launch from (read at startup).
• For an organization: set "disableWorkflows": true in managed settings, or use the toggle on the Claude Code admin settings page.
• No setting disables ultracode alone, and an effort cap (maxEffortLevel) does not rule it out: since v2.1.284 it stays on at the capped level. To rule it out, turn workflows off.

When workflows are off, the bundled commands and /workflow-authoring disappear, the keyword stops triggering, and ultracode leaves the /effort menu. A run already in progress keeps going.

Where to go next with dynamic workflows

Custom subagents Define the specialized workers a workflow fans out to, with their own model and tool allowlist.

Goal workflows with /goal When the end state is one pass/fail condition, set a goal instead of writing a fan-out.

Multi-agent orchestration patterns Fan-out/fan-in, best-of-N with a judge and writer/reviewer separation across Claude Code, Codex and Cursor.

Agent view Run and monitor many background sessions from one dashboard, and keep workflows running after you exit.