Omniscio

OmniscioGuidesClaude Code workflows

Claude Code workflows: many subagents, one script

A workflow is the moment a multi-agent job stops being a conversation and becomes a program. Claude writes the orchestration as a script, the script decides what runs next, and your session stays free while it does.

This page covers what a workflow buys you over subagents and agent teams, how to start and watch one, what the runtime will not let it do, what it costs, and what survives when you stop it.

Last checked against Anthropic's Claude Code documentation on November 18, 2026. By the Omniscio team. Updated .

What a workflow is

A dynamic workflow is a JavaScript script that orchestrates many subagents at once. Claude writes the script for the task you describe, and a runtime executes it in the background while your session stays responsive.

Reach for one when a task needs more agents than a conversation can coordinate, or when you want the orchestration itself written down. Anthropic's examples are a codebase-wide bug sweep, a 500-file migration, a research question whose sources must be cross-checked, and a hard plan worth drafting from several independent angles.

The part that matters is where the plan lives. In a workflow the script holds the loop, the branching and the intermediate results, so Claude's context holds only the final answer — and the same orchestration can be run again next week against a different codebase.

Source: the introduction and "When to use a workflow" in Anthropic's workflows page, read November 18, 2026.

Workflow, subagents, skills or teams

All four can carry a multi-step task. Anthropic's distinction is who decides what runs next, and the difference shows up as scale and as interruption:

What each route is good at.
RouteWho decides what runs nextScaleWhen interrupted
SubagentsClaude, turn by turnA few delegated tasks per turnThe turn restarts
SkillsClaude, following the promptSame as subagentsThe turn restarts
Agent teamsA lead agent, turn by turnA handful of long-running peersTeammates keep running
WorkflowsThe scriptDozens to hundreds of agents per runResumable in the same session

A script can also hold a repeatable quality pattern, not just more agents: independent agents can review each other's findings before anything is reported, or a plan can be drafted from several angles and weighed.

Moving the plan into code has a cost too. A workflow cannot ask you a question mid-run, which is why Anthropic's advice for a job needing sign-off between stages is to run each stage as its own workflow.

Source: "When to use a workflow" and "Behavior and limits" in Anthropic's workflows page, read November 18, 2026.

See one run: /deep-research

Claude Code bundles one workflow, and it is the fastest way to see the shape of a run:

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

It fans out web searches across several angles, fetches and cross-checks what it finds, votes on each claim, and returns a cited report with the claims that did not survive cross-checking already removed. When a verifier cannot check a claim — after a rate limit, say — the report lists it as unverified rather than counting it as refuted.

Claude Code asks whether to allow the workflow; the exact prompt depends on your permission mode. Then the run goes to the background and your session is free again. The one requirement is Anthropic's: the WebSearch tool has to be available.

Sources: "Run a bundled workflow" and "Bundled workflows" in Anthropic's workflows page, read November 18, 2026.

Ask for a workflow

For one task, without changing the session's effort level, include the keyword in the prompt:

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

Asking in your own words works the same way — "use a workflow", "run a workflow" — because Claude treats a direct request as the same opt-in. The keyword only chooses how the work is structured: the agents' tool calls get the same permission checks and sandboxing as any other call in the session.

Two limits on where the keyword counts. It is an opt-in only in a prompt you type yourself: at the interactive prompt, in an IDE panel, in a Remote Control client, or from an SDK application that stamps the input as human. It does not start a workflow when it arrives through -p, a scheduled task prompt, a webhook, or a pull request comment.

If it triggers and you did not mean it, backspace while the cursor sits right after the highlighted keyword, or press Option+W on macOS and Alt+W elsewhere.

Source: "Ask for a workflow in your prompt" on Anthropic's workflows page, read November 18, 2026.

Let Claude decide: ultracode

/effort ultracode

With ultracode on, Claude plans a workflow for each substantive task instead of waiting to be asked. One request can become several workflows in a row: one to understand the code, one to make the change, one to verify it.

That is a real cost decision, not a preference. Every task in the session then uses more tokens and takes longer, and on a subscription plan those tokens draw on your usage limits, so a session with ultracode on reaches a limit sooner than the same work without it. Anthropic also notes what turning it on waives: the large-workflow warning does not appear, the session's concurrent-subagent limit is not enforced for the subagents Claude spawns — a separate cap from the workflow runtime's 16 — and in auto mode you are not asked to approve the first launch.

/effort ultracode lasts the session. To start every session that way, set the ultracode setting, and turn it off with /effort ultracode off when you go back to routine work.

Source: "Let Claude decide with ultracode" on Anthropic's workflows page, read November 18, 2026.

Watch it, pause it, stop it

Run /workflows to list running and finished runs, then open one. A one-line progress summary also sits in the task panel below the input box; press the down arrow to focus it and Enter to expand.

Inside the progress view the keys matter more than the labels:

  • ↑ and ↓ select a phase or an agent; Enter drills in and expands a detail.
  • f filters the agent list by status, cycling each time you press it.
  • p pauses or resumes the whole run.
  • x stops the selected agent, or the whole workflow when the focus is on the run.
  • r restarts the selected running agent; s saves the run's script.

Stopping from the list without opening it is the same key: select the run, press x. A stopped run stays in the task panel while any of its agents are still running, and stopping again re-signals them.

Source: "Watch the run" and "Manage runs" in Anthropic's workflows page, read November 18, 2026.

Save it as a command

When a run does what you wanted, keep it. Select the run in /workflows, press s, and choose where it lives: .claude/workflows/ in the project, shared with everyone who clones the repository, or ~/.claude/workflows/ in your home directory, available everywhere and visible only to you. It then runs as /name in later sessions.

Three details are worth knowing before you rely on it. A project workflow beats a personal one when both share a name. In a monorepo the script saves into the closest existing .claude/workflows/ between your working directory and the repository root, and loads from every such directory along that path. And Claude Code refuses to write through a symlink rather than following one.

A saved workflow can take input through args, read inside the script as a global of that name, so a list of issue numbers or target paths arrives as structured data you can call array methods on.

Sources: "Save the workflow for reuse" and "Pass input to a saved workflow" in Anthropic's workflows page, read November 18, 2026.

What the runtime will not do

The runtime's constraints, and why each exists.
ConstraintWhat it means
No mid-run user inputIt pauses on its own only for an agent permission prompt or a usage-limit wait. Run each stage as its own workflow if you need sign-off.
No filesystem or shell access from the scriptThe agents read, write and run commands. The script coordinates them.
No module loadingA script containing import() fails before the run starts. Put work that needs a library in an agent's task.
16 concurrent agents by defaultFewer when Claude Code has fewer CPUs, including in a CPU-limited container. CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS takes 1 to 256 on v2.1.269 or later.
4,096 items per parallel() or pipeline()A longer list is rejected rather than silently truncated.
1,000 agents per runA ceiling on runaway loops.

One more behaviour sits inside those caps: in a fan-out, agents that share the first agent's prompt-cache prefix wait up to five seconds behind it, so they read the prefix it cached instead of each processing it uncached. CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS changes the wait, and 0 disables it.

Sources: "Prompt caching in a fan-out" and "Behavior and limits" in Anthropic's workflows page, read November 18, 2026.

What a run costs

A workflow spawns many agents, so one run can use meaningfully more tokens than working the same task in conversation, and runs count toward your plan's usage and rate limits.

Anthropic's advice for gauging it first: run the workflow on a small slice — one directory instead of the whole repository, a narrow question instead of a broad one. The /workflows view shows each agent's token usage as the run progresses, and you can stop there, usually without losing completed work.

Claude Code also flags the ones that grow. Past 25 agents, or a projected total for the run past 1.5 million tokens, the progress line shows a Large workflow warning. It is advisory — it neither pauses nor limits the run. Turning ultracode on suppresses it, because ultracode is already an opt-in to large runs.

The setting that changes the shape is the size guideline: small aims under 5 agents, medium under 10, large under 50, and unrestricted sets no target. It is advice to Claude rather than a cap. Set it in the Dynamic workflow size row of /config, or as workflowSizeGuideline in a settings file, which takes precedence.

Sources: "Cost" and "Set a size guideline" in Anthropic's workflows page, read November 18, 2026.

What survives a stop

Resume a paused run from /workflows with p. For a run you stopped, ask Claude to relaunch the workflow with the same script — and if agents from the stopped run have not exited yet, Claude Code refuses until they have, so two copies never run side by side.

On replay, Claude Code walks the agents in the order they start and each one either returns its saved result or runs again:

  • Completed returns its saved result — until the first agent whose prompt differs from the last run, because you edited the script or an earlier agent returned something new. That one runs again, and so does every agent after it.
  • Still running when you stopped starts over. Stopping the run does not count any agent as failed.
  • Failed runs again, along with every agent the script starts after it — even ones that had completed. Stopping a single agent with x counts as failing it.

That last rule is the expensive one in practice. If a script starts A, B, C and D in order and B fails, relaunching returns A from its saved result and runs B, C and D again.

Source: "Resume after a pause" and "Which agents run again" in Anthropic's workflows page, read November 18, 2026.

Turning workflows off

Three ways for yourself. Toggle Dynamic workflows off in /config, or set "disableWorkflows": true in ~/.claude/settings.json — both persist across sessions. Or set CLAUDE_CODE_DISABLE_WORKFLOWS=1, which is read at startup, so it applies wherever you set it. For a whole organization, the same key in managed settings or the toggle on Claude's admin settings page.

What stops: /workflows, the workflow commands and the workflow-authoring skill disappear, the ultracode keyword stops triggering, and the Ultracode toggle leaves /effort. A run already in progress keeps going.

One asymmetry is worth knowing. Turning workflows off also takes ultracode away, but no managed setting rules out ultracode on its own: wherever it is available, a user can turn it on.

Source: "Turn workflows off" in Anthropic's workflows page, read November 18, 2026.

Where these answers come from

Common questions

How is a workflow different from subagents or agent teams?

The plan lives in a script rather than in Claude's turn-by-turn judgement. The script holds the loop, the branching and the intermediate results, so Claude's context holds only the final answer and the orchestration can be repeated.

How many agents can one workflow run?

16 concurrently by default — fewer on fewer CPUs — and 1,000 in total per run. A single parallel() or pipeline() call is capped at 4,096 items.

Can I stop a workflow and keep the finished work?

Yes. Completed agents return their saved results on replay. An agent that was still running when you stopped starts over; a failed agent runs again along with everything the script starts after it.

Does a workflow count against my usage limits?

Yes, and one run can use meaningfully more tokens than doing the same task in conversation. Anthropic's advice is to try a small slice first and watch the per-agent usage in /workflows.