Claude Code Dynamic Workflows Explained: Ultracode, /workflows, and the 1,000-Agent Cap (2026)

- Every number and version threshold here was cross-checked against the official docs (code.claude.com/docs/en/workflows) at the time of writing (08/2026); this feature changes with nearly every release, so verify the live docs before you depend on it.

This is advanced content - written for readers already using Claude Code with subagents and skills; it doesn't re-teach the basics. If you're not sure what a subagent is, read how Claude Code subagents work or what a Claude Code skill is first.

What a dynamic workflow actually is

A dynamic workflow isn't a separate UI feature - it's a mechanism: once triggered, Claude writes a JavaScript script describing the plan (what runs first, what runs in parallel, what waits on a prior step's result). That script fans work out to many background subagents, and Claude keeps only the final result in the main session's context - not every subagent's full reasoning trail.

Contrast that with a normal turn, even one where you've asked Claude to delegate to a subagent: the main session still has to hold each subagent's output in its own context to decide what happens next, and if you close the session mid-task, that in-progress reasoning is gone. A dynamic workflow moves the "what happens next" decision out of the conversation entirely and into the script, which is what makes a 1,000-agent run possible without blowing up the main session's context window.

An illustrative example to make the mechanism concrete (not real measured data, just the logic): you ask Claude to audit the whole src/ directory for security issues. The script it writes might look like "hand each subdirectory to its own agent to scan, any agent that finds an issue reports it with evidence, one final agent aggregates everything into a table" - that entire branching, waiting, and aggregation logic lives in the script file, not in Claude's working memory the way it does when you orchestrate subagents by hand.

Requirement: Claude Code v2.1.154 or newer (version threshold - verify your own version before depending on this), available on every paid plan plus API/Bedrock/Vertex/Microsoft Foundry. On Pro, it's not on by default - you turn it on manually via the "Dynamic workflows" row in /config. Don't confuse this with auto-mode (on by default since 2026-08-14) - that's a different feature entirely, unrelated to dynamic workflows, even though both landed in roughly the same run of releases.

Requires Claude Code v2.1.154+ (verify your actual version first); runs on every paid plan plus API/Bedrock/Vertex/Microsoft Foundry; Pro users must enable it manually via /config, it is not on by default.

Two ways to trigger it

There are two ways to call up a dynamic workflow, depending on whether you want it for one task or for the whole session.

A history detail most write-ups skip: the typed keyword used to be workflow before v2.1.160, then it was renamed to ultracode at v2.1.160. But the natural-language phrasing ("use a workflow for this") has always worked in both eras - it never depended on the exact keyword. If you see older docs or posts saying "type workflow," that's the pre-v2.1.160 naming.

A gotcha worth remembering: the keyword only fires from typed, human input - not through the -p flag, not through Agent SDK non-human input, not through scheduled tasks, and not through webhook/PR-comment relays. If you're scripting Claude Code through any of those channels, typing "ultracode" somewhere won't trigger a dynamic workflow on its own.

Which method to pick depends on what you're doing. For one big task in an otherwise normal session (say, "ultracode: audit all error handling in the api/ directory"), typing the keyword for just that turn is enough - the rest of the session runs as usual, without extra reasoning overhead on the small stuff. If you already know the whole session is going to be heavy work (a day set aside for a migration or an audit), /effort ultracode saves you from retyping the keyword every turn - but the trade-off is that every substantive task in that session gets pushed into xhigh reasoning, including things you never intended to run as a workflow.

Try the built-in /deep-research workflow first

The fastest way to see a dynamic workflow run for real, with zero setup, is the built-in /deep-research workflow:

1. Run /deep-research <your question>.
2. Approve the plan Claude proposes before it runs.
3. Watch progress with /workflows.
4. Read the final report - it's cited.

The interesting part: claims that fail cross-checking get filtered out, and claims that can't be verified get marked unverified rather than flatly refuted - a different failure mode than Claude confidently inventing a single answer. Note this workflow needs the WebSearch tool enabled. If you're still fuzzy on what a subagent is, read how Claude Code subagents work before the next section.

Why it's worth trying first: it's the one workflow you don't have to write the orchestration prompt for - Anthropic already packaged the "find sources → cross-check → filter weak claims → write a cited report" logic inside it. Run it once on a concrete technical question (say, "compare how Next.js 16 and Remix handle streaming SSR") and you'll see the general shape every dynamic workflow follows: a plan approved up front, several agents running in parallel that you don't have to babysit step by step, and a final result that's already been filtered instead of a single unverified answer.

Watch and manage a run - /workflows

Type /workflows to open the live tracking view: current phase, how many agents are running, total tokens spent, elapsed time - all in one screen that updates live.

This view matters more than it looks: it's the only way to know how much a run is "eating" before it eats your weekly budget - more on cost below. Think of it like letting a CI pipeline run without a dashboard: it can still finish fine unattended, but it's worth keeping an eye on a large run the first few times, at least until you have a feel for how much token it burns on the kind of task you typically hand it.

The numbers to know before you turn this on

This is the section worth reading closely before you point this feature at anything big, since none of these numbers are obvious from the UI until you go looking.

Hard caps: up to 1,000 agents per run (prevents a runaway loop from running forever), and up to 16 concurrent agents (fewer on CPU-limited machines/containers). The 1,000 figure is a ceiling on the whole run, not a target - most real tasks finish with far fewer agents; it exists specifically to stop a badly-scoped script from spawning agents indefinitely if a stop condition never triggers.

Size guidelines are advisory, not a hard limit (requires v2.1.202+ - version threshold, verify before depending on it). You can set one if you want to force Claude to keep the agent count lower than the default.

The Large workflow warning: fires when a run exceeds 25 agents OR 1.5M projected tokens (the 25 changes if you've set your own size guideline). It's advisory only - it doesn't pause the run. Sessions already running /effort ultracode won't show this warning, since opting into that mode already means you've accepted large runs from the start.

Putting the numbers together: an audit scoped to a directory with a few dozen files, on the default medium size guideline (under 15 agents), will almost never touch the 25-agent warning threshold. But a migration spanning 200+ files across a whole repo can easily blow past both 25 agents and 1.5M tokens - at that point you're better off deliberately setting the size guideline to large (or accepting the warning) instead of being surprised mid-run. Put another way, the 1,000/16/25 numbers aren't there to scare you off the feature - they're there so you can estimate "how big is what I'm about to hand it" before you hit enter.

Workflows vs subagents vs skills vs agent teams - who holds the plan

This is the most important question if you already use subagents and skills: these four differ in who holds the orchestration plan, not in which one is "stronger."

In plain terms: subagents and skills let Claude decide each step itself, bounded by that session's context window. Agent teams (experimental - see agent teams for multi-session collaboration) is a lead agent supervising peer agents through a shared task list, suited to long collaborative sessions. A dynamic workflow is different because the plan lives in a script, not in Claude's context - so the main context only has to hold the final answer, not the whole process.

Quick pick: routine delegation → subagents/skills. A long, collaborative session that needs ongoing supervision → agent teams. A task bigger than one context window, or one that needs adversarial cross-checking (multiple agents verifying each other's results) → a dynamic workflow. Want to define your own reusable subagent? See the subagent guide; need the skills basics first? See what a Claude Code skill is.

The easiest mix-up between these four: subagents and skills both let the main session's Claude make the call - they differ only in that a skill is an instruction bundle loaded by context while a subagent is a separate "persona" invoked to do one job and hand results back. Both live and die by that session's context window: interrupt the session mid-way and the progress is gone. Agent teams and dynamic workflows both escape that limit, but in different ways - agent teams escape it by letting several sessions collaborate through a shared task list that outlives any single agent's context; dynamic workflows escape it by pulling the plan entirely out of context and turning it into an object you can save, version in git, and rerun identically at any time - which is exactly why it fits large, repeatable work better than an exploratory conversation.

Save a workflow you like as a reusable command

Got a run you like? Save it so you don't have Claude rewrite the script from scratch next time:

1. Open /workflows, select the run you want to keep.
2. Press s to save it.
3. Pick where: .claude/workflows/ (shared, project-scoped) or ~/.claude/workflows/ (personal).
4. The saved workflow becomes a /<name> command, and it can take input through an args parameter.

If you work on a team, a workflow can also ship inside a plugin (a workflows/ directory), called with a namespaced /plugin-name:workflow-name - handy for sharing an orchestration script across the whole team instead of copy-pasting commands.

The nice part of saving a workflow as a file: since it lives as a plain text file under .claude/workflows/, you commit it to git like anything else in the repo. A teammate pulling the branch gets the same workflow automatically - Claude doesn't have to "relearn" the audit or migration approach you already tuned. This is also the clearest difference from subagents and skills: a subagent you like using doesn't automatically become something a teammate can invoke identically - a saved dynamic workflow does.

The token-cost reality

To be straight: the official docs give no fixed dollar figure for dynamic workflows, and I'm not inventing one just to make this section feel complete. There's a story circulating - something like "a $200/month Max plan burned 20% of a weekly limit in one day" - I checked it, and it traces back to a blog post synthesizing a social-media report, not a primary or independently verifiable source, so I'm not repeating that number here.

What the docs do say plainly: the two hard caps (1,000 agents / 16 concurrent) exist specifically to bound runaway cost. Every subagent uses the main session's model, unless the script or the CLAUDE_CODE_SUBAGENT_MODEL variable routes it elsewhere.

Practical, docs-backed advice:

• Test on a small slice first (one directory, not the whole repo) before a full run.
• Watch per-agent token totals live in /workflows while a run is in progress.
• Drop the size guideline to small if you want to force a lower agent count than the default.

Why I'm not inventing an estimate of my own: real cost depends on too many variables at once - how long each subtask runs, which model the session is set to, how many agents the script itself decides to spawn per branch - so any single "average" figure would mislead more than it would help. A far safer approach is to measure your own workload: run a small pass, read the token count in /workflows, and scale roughly linearly to the size you actually plan to run - rather than trusting a number somebody picked up off social media.

Does AgentKit give you this? (the honest answer)

A question worth asking if you already use AgentKit: does AgentKit have its own "workflow" thing, and is it the same as this? Straight answer: no. Dynamic Workflows is a native Claude Code engine - the exact JavaScript-script agent fan-out mechanism this article describes. AgentKit doesn't ship that engine, and it doesn't have an ak-side equivalent.

I checked docs.agentkit.best/en/beta/reference/cli directly (08/2026): the word "workflow" on AgentKit's site is generic marketing copy for its skill bundle, and the ak orchestrate command is a completely different feature - a job graph for external CLI tools, macOS-only, unrelated to Claude Code's dynamic workflows.

So what does AgentKit actually give you? A curated, licensed set of skills and subagent personas (called through /ak:cook and similar commands) that you can point a dynamic workflow at - whether you write the script yourself or let Claude write it - used as individual agent tasks, same as any other subagent. In short: buy AgentKit for the prebuilt skill/persona layer; use Dynamic Workflows (free, native) for the orchestration-at-scale layer. They stack, they don't compete. Read the full AgentKit review for more.

An illustrative example of how the two layers fit together (not a measured result, just a usage pattern): a dynamic workflow auditing security across five microservices could hand each service to an agent running AgentKit's ak-security skill, then have one final agent aggregate the findings from all five. The orchestration script (what runs in parallel, what waits on what) belongs to Dynamic Workflows; the domain know-how inside each agent belongs to the skill you bought. Remove AgentKit and the workflow still runs - each agent just falls back on Claude's general knowledge instead of a skill purpose-built for that job.

Should you turn this on today

There's no universal answer here, which is honestly the more useful takeaway than a hard yes/no - the right call depends on how big and how repeatable your next task actually is, not on whether the feature is new and exciting. Short verdict: try the ultracode keyword on one real, bounded task first (a single-directory audit, not a whole-repo migration), before deciding to set /effort ultracode for the whole session. Good fit for: large migrations, codebase-wide audits, research that needs cross-checking across sources. Skip it for: routine small edits, or if you're on a cost-sensitive Pro plan without headroom.

A quick checklist before you hit enter: (1) is the task actually big enough to split into independent branches, or is it really a sequential chain you could do faster by hand; (2) are you actually going to keep /workflows open to watch it, or planning to walk away; (3) if this run fails partway through, are you fine with the tokens already spent. If all three answer "yes," go ahead and turn it on; if question one is "no," a plain subagent is usually still faster and cheaper.

FAQ

What is ultracode in Claude Code?

Ultracode is the keyword (and effort setting) that triggers a dynamic workflow - Claude writing a JS script that fans a task out to up to 1,000 background subagents. Typing "ultracode" or phrasing it naturally, like "use a workflow for this," both trigger it.

How many agents can one dynamic workflow run?

Up to 1,000 agents per run, with up to 16 running concurrently (fewer on CPU-limited machines/containers). These are hard caps, not recommendations.

What triggers the Large workflow warning?

A run exceeding 25 agents or 1.5M projected tokens (the 25 changes based on your own size guideline). It's advisory only and doesn't pause the run.

Is a dynamic workflow the same as agent teams?

No. Agent teams is a lead agent supervising peer agents through a shared task list, suited to long collaborative sessions (an experimental feature). A dynamic workflow's plan lives in a pre-written script instead of Claude's context, and can be saved and rerun identically - agent teams generally can't be replayed the same way twice.

Do I need a paid plan?

Yes. It runs on every paid plan plus API/Bedrock/Vertex/Microsoft Foundry. Pro users must enable it manually via the "Dynamic workflows" row in /config; it isn't on by default.

Does AgentKit include Claude Code's dynamic workflows?

No. Dynamic Workflows is a native, free Claude Code engine. AgentKit is a separate, paid set of skills and subagent personas you can use as individual agent tasks inside a dynamic workflow - the two complement each other, they aren't the same thing.

Conclusion

Dynamic workflows is a power-user feature: real caps (1,000 agents/16 concurrent), an advisory warning at 25 agents/1.5M tokens, and it pairs with - rather than replaces - AgentKit's skill layer. Try it on something small before turning it on for a whole session, and keep /workflows open so you always know what you're spending. The version gates move fast, so treat every threshold in this article as a starting point, not gospel - re-check the live docs the day you actually flip this on for something that matters.