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 .
On this page
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:
| Route | Who decides what runs next | Scale | When interrupted |
|---|---|---|---|
| Subagents | Claude, turn by turn | A few delegated tasks per turn | The turn restarts |
| Skills | Claude, following the prompt | Same as subagents | The turn restarts |
| Agent teams | A lead agent, turn by turn | A handful of long-running peers | Teammates keep running |
| Workflows | The script | Dozens to hundreds of agents per run | Resumable 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 checksAsking 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 ultracodeWith 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;Enterdrills in and expands a detail.ffilters the agent list by status, cycling each time you press it.ppauses or resumes the whole run.xstops the selected agent, or the whole workflow when the focus is on the run.rrestarts the selected running agent;ssaves 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
| Constraint | What it means |
|---|---|
| No mid-run user input | It 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 script | The agents read, write and run commands. The script coordinates them. |
| No module loading | A script containing import() fails before the run starts. Put work that needs a library in an agent's task. |
| 16 concurrent agents by default | Fewer 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 run | A 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
xcounts 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
- Everything on this page: Orchestrate subagents at scale with dynamic workflows, read November 18, 2026.
- The worker a workflow orchestrates: Claude Code subagents.
- The route with a lead agent instead of a script: Claude Code agent teams.
- The effort levels ultracode sits beside: Claude Code effort levels.
- The context budget a fan-out protects: the context window.
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.