AIDiveTL;DR and verdict
- Ultracode does not make Claude Code smarter. It changes what the model is told and removes three guards, so a run spends more and stops later.
- The rule: fan out only when a test suite or a rule set judges the output and the job splits into independent pieces. Everything else, run plain at high.
- Five settings cap a run: the workflow size guideline set to small, a concurrent-agent ceiling of 4, one cheaper model for every workflow agent, the keyword instead of the toggle, and auto-continue at the usage limit switched off.
- The two files that carry the caps are
settings.jsonandultracode-caps.sh. The checklist iswhen-to-fan-out.md. The measured pairs are inpaired-runs.csv. - The size guideline is advice, not a cap. On our own run it said fewer than 5 agents and the run used 9.
What the sources say
Keyword versus toggle. Typing ultracode in a prompt opts that one task into a workflow. Asking in your own words, such as "use a workflow", works as the same opt-in s1. The keyword does nothing in a prompt passed with -p, in unstamped Agent SDK input, or in a scheduled task s1. The toggle is different. With ultracode on, Claude plans a workflow for each substantive task, and one request can become several workflows in a row s1. The docs add that a session with ultracode on reaches a session or weekly limit sooner than the same work with it off s1.
The injected sentence. With ultracode on, the workflow-authoring reference says: "author and run a workflow for every substantive task by default. The goal is the most exhaustive, correct answer you can produce" and that "token cost is not a constraint." The same text is quoted in a public issue titled "Ultracode overrides the workflow size guideline" s8. Each workflow in a sequence gets its own agent budget, so four phases of 15 agents make 60 agents while no single workflow breaks the guideline s8.
The three guards. Ultracode turns off three checks. The Large workflow warning does not appear. The session's concurrent subagent limit is not enforced for subagents Claude spawns with the Agent tool. In auto permission mode you are not asked to approve the first workflow launch s1.
The size guideline. Small means fewer than 5 agents, medium fewer than 10, large fewer than 50. The default is medium, or small on a Pro plan with v2.1.271 or later. Claude Code sends it to the model as advice, not a cap, so a prompt that asks for another scale still overrides it s1. The hard limits are 16 concurrent agents by default and 1,000 agents per run. The large-workflow warning fires above 25 agents or 1.5 million projected tokens, and it only warns s1.
Our own run. We typed the keyword on a sandbox of two files and 16 lines of code, with the size guideline set to small, and asked for a read-only review. The run used 9 agents: 2 finders and 7 verifiers. Each finder read about 45.2k tokens. We made no plain run of the same prompt, so we have no paired figure of our own.
The paired test. On a $200 plan, a developer gave the same spec to a plain run and an ultracode run. Both passed 136/136 hidden checks. The plain run finished in 25 min at 8% of the 5-hour limit. The ultracode run was cut off at 76 min with 18% gone, and it used 12 agents in two teams (9 and 3), not 1,000. Per minute the burn was about equal: it just didn't stop s3.
Three more pairs on a Pro plan. Single agent against workflow, same findings: 115k vs 972k tokens, 52k vs 936k, and 102k vs 683k. The /usage meter moved 4 vs 12, 7 vs 12 and 4 vs 8 points, which the author sums up as roughly two times the quota, up to three. Wall time on the Opus plan script was 173 s vs 178 s. On four independent research jobs, parallel was 1.6x faster for 2.3x the tokens s4.
The 30x pair. One agent at xhigh took 1 h 13 m for about $18 at API prices. Max with ultracode took 9 h 14 m, with 40 subagents, for about $554. One run each, API list prices, not billed on a subscription s11.
What a pair looks like. A public test repo holds one single-agent versus workflow pair on the same task. The single agent used 181,646 tokens, the workflow 1,326,703. The cost at API price was $0.2678 against $1.3744. The wall time was 43 s against 80 s, and the session meter moved +0 against +12 points s22. That is one pair, so read it as a shape and not as a law. The docs list subagents and workflows as a token driver: every agent a workflow spawns sends its own requests on top of the main conversation's s5. Anthropic's research team measured about 4x more tokens for an agent than for a chat, and about 15x for a multi-agent system s20.
Where it pays: Bun. Bun was rewritten from Zig to Rust with about 50 dynamic workflows run continuously over 11 days. The source was 535,496 lines of Zig, and the port went from start to 100% of the test suite passing on all platforms in 11 days s19. The judge was an existing test suite.
Where it pays: the bug hunt. Anthropic planted 70 bugs in a 116k-line codebase. Across 3 runs a single agent found 14, 15 and 27. A workflow found 66 in each of its 3 runs s24. That test ran on Managed Agents, the API product, not on Claude Code. Anthropic gave no cost for it and advises starting with a scoped task s24. The launch blog says most traditional coding tasks do not need a panel of 5 reviewers s2.
The runaway run. A model-written script on a Max 20x plan started 221 agents in 51 minutes. After the first session-limit error, 189 more agents were started. The filer's table counts 47,465,299 tokens including cache s7. Two caveats from the filer: the 189 later agents had no recorded model responses, and the script's fallback kept dispatching when a merge returned nothing. That run was on v2.1.266, before the pause at the usage limit s7. A second public report describes two workflows of 56 and 104 agents, 1,472,855 and 1,752,360 tokens, where 92 of 160 agents failed with the session limit s21. The filer says ultracode was reported on without the user enabling it.
The levers. CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS takes a value from 1 to 256 and needs v2.1.269 s10. CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL runs every workflow agent on one model while other subagents keep theirs, from v2.1.296 s18. With autoContinueAtUsageLimit on, a run that hits the limit pauses and resumes at the reset, up to two waits, and the third time the agent fails. With it off, the affected agents fail at the wall s1. The launch blog says a budget in the prompt, such as "use 10k tokens", sets the cap s2. The /workflows view shows each agent's token usage, and x stops the run s1. /usage flags behaviors that account for 10% or more of recent usage, and v2.1.299 added warnings for workflows s5 s18.
The cap kit
The settings block. Cap 1 is the size guideline, cap 4 is ultracode kept false so the keyword is the only way in, and cap 5 is auto-continue off. Put it in .claude/settings.json or any settings file. The key workflowSizeGuideline works in any settings file from v2.1.219 s1.
settings.json
{
"workflowSizeGuideline": "small",
"ultracode": false,
"autoContinueAtUsageLimit": false
}
The env lines. Caps 2 and 3. Replace the placeholder with the full id of the model you want your workflow agents to run on.
ultracode-caps.sh
#!/usr/bin/env bash
# Source this file before you launch Claude Code: `source ultracode-caps.sh && claude`.
# These two lines are caps 2 and 3 of the five. Caps 1, 4 and 5 live in settings.json.
# Cap 2: at most 4 workflow agents run at once. The default is 16 (fewer on a machine
# with few CPUs). Accepted values are 1 to 256. Needs Claude Code v2.1.269 or later.
export CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS=4
# Cap 3: run every workflow agent on one cheaper model, while your other subagents
# keep theirs. Replace the placeholder with the full model id you want to pay for.
# Needs Claude Code v2.1.296 or later.
export CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL="<your-cheaper-model-id>"
# Optional kill switch for a shared machine: no workflows at all.
# export CLAUDE_CODE_DISABLE_WORKFLOWS=1
The checklist you run before you type the keyword.
when-to-fan-out.md
# When to fan out: the two-condition checklist
Fan out (use the ultracode keyword in one prompt) only if both answers are yes.
1. Does a test suite or a rule set judge the output?
- [ ] A suite that already exists and says pass or fail without anyone's opinion.
- [ ] Or a written rule file the output is reviewed against.
2. Does the job split into independent pieces?
- [ ] No piece waits on the result of another piece.
- [ ] Each piece can be checked on its own.
If either answer is no, run plain at high effort. A plain run costs one bill. A
workflow costs one bill per agent.
Jobs that usually pass both tests:
- A port or migration across many files with a test suite as the judge.
- A review of a whole codebase against a rule file.
- A translation of many files with the same prompt.
- A cleanup pass over a pile of similar documents.
Jobs that usually fail one of them:
- A small feature, a bug fix, a refactor of one module.
- Anything where "good" is a matter of taste.
- A chain of steps where each one needs the previous result.
Before you start:
- [ ] Run a slice first (one folder, ten files) and read the token total.
- [ ] Put a budget in the prompt, for example "use 10k tokens".
- [ ] Open /workflows and watch per-agent tokens. Press x to stop.
- [ ] After the run, open /usage and read the share that went to workflows.
The measured pairs and cases from the sources, one row each, with the source id.
paired-runs.csv
source_id,run,measure,baseline,workflow_or_fanout,note
s22,rebuild-your-claude-md pair (rep 2),tokens,181646,1326703,"all four usage fields summed, 14 agent transcripts on the workflow side"
s22,rebuild-your-claude-md pair (rep 2),API cost in USD,0.2678,1.3744,single agent vs workflow
s22,rebuild-your-claude-md pair (rep 2),wall time in seconds,43,80,single agent vs workflow
s22,rebuild-your-claude-md pair (rep 2),session meter points,+0,+12,"/usage before to after: 17% to 17% vs 19% to 31%"
s24,70 planted bugs in 116k lines,bugs found,"14, 15 and 27 (3 runs)","66 in each of 3 runs","Managed Agents, not Claude Code; no cost given"
s19,Bun port from Zig to Rust,test suite passing,,100%,"about 50 dynamic workflows, 11 days, 535,496 lines of Zig"
s6,fixed worker and gate files,tokens for workflow execution and monitoring,100%,about 20%,"self-reported, no plan stated; runs 5 to 6 hours down to 20 to 40 minutes"
s7,runaway run on Max 20x,agents started,,221,"51 minutes; 189 started after the first session-limit error; 47,465,299 tokens including cache"
s21,ultracode reported on without the user enabling it,agents started,,"56 and 104","1,472,855 and 1,752,360 tokens; 92 of 160 agents failed with the session limit"
s20,multi-agent research system,tokens vs a chat,about 4x for an agent,about 15x for multi-agent,Anthropic's own data
s3,same spec on a $200 plan,hidden checks passed,136/136,136/136,"both runs perfect"
s3,same spec on a $200 plan,time and 5-hour limit used,"25 min, 8%","76 min (cut off), 18%","12 agents in two teams (9 and 3)"
s4,Opus plan script,tokens,115k,972k,"Pro plan; /usage 4 vs 12 points; 173 s vs 178 s"
s4,compact script,tokens,52k,936k,"Pro plan; /usage 7 vs 12 points"
s4,Claude.md script,tokens,102k,683k,"Pro plan; /usage 4 vs 8 points"
s4,four independent research jobs,time and tokens,"102 s, about 33k","about 64 s, 76k","parallel 1.6x faster for 2.3x tokens"
s11,Cybercity,time and API cost,"1 h 13 m, about $18 (1 agent)","9 h 14 m, about $554 (40 subagents)","xhigh vs max with ultracode; one run each; API list prices"
Two notes on the kit. The ultracode key only matters if you would otherwise start sessions with the toggle on, and keeping it false means each fan-out is a decision you make in one prompt. Turning workflows off entirely removes the keyword and the toggle: set "disableWorkflows": true in ~/.claude/settings.json s1.
Do this Monday
- Copy
settings.jsoninto your project settings and check/configshows the size guideline as small. - Source
ultracode-caps.shin the shell you launch Claude Code from, with a real model id in place of the placeholder. - Check that the
ultracodetoggle is off in/effort, and use the keyword in a single prompt when you want a fan-out. - Before any fan-out, answer the two questions in
when-to-fan-out.md. If one answer is no, run plain at high. - Run a slice first and read the token total in
/workflowsbefore you widen the job. - Add a budget to the prompt, for example "use 10k tokens".
- Keep
/workflowsopen on the first run and pressxif the agent count climbs past what you expected. - After the run, open
/usageand note the share that went to workflows.
Go further
Fix the worker and the gate instead of letting the model write them. One Hacker News post reports getting the token spend for workflow execution and monitoring to about 20% of what it was, with workflows that took 5 to 6 hours now taking 20 to 40 minutes. It is self-reported and states no plan s6. The method has two parts. A workflow-worker agent file gets one piece of the plan and tight permissions to write and run tests for its own part only. A workflow-gate agent file takes the results of the parallel agents, and the serial checks move into a Makefile with two targets: make workflow-serial-gate checks the git tree and runs tests for what changed, and make workflow-final-gate runs clean tests on everything s6. The gate check that used to take 10 minutes for complex plans now takes a second, per the same post. The 20% covers execution and monitoring, not plan creation or implementation. To try it, write the two agent files once, keep them in the repo, and point your workflow prompt at them.
Read the runaway report before you trust a generated script. The issue shows a per-phase table and the one pattern behind the 189 extra agents: when a merge agent returns nothing, the script falls back to the raw list and carries on s7. Ask the model for scripts that stop on a failed agent. Keep auto-continue off on any run you do not watch.
Know why the guideline loses. Issue 92631 shows the guideline text next to the ultracode sentence, and why the second wins when they disagree s8. If you want a hard ceiling, the concurrency variable limits how many agents run at once, and the budget in the prompt limits what they spend.
Use the launch thread for the wide jobs. The sharpest day-one pushback is in the launch thread, with comments such as "an exciting new way to burn up as many tokens as possible" and "Quantity of output is not the issue right now. Quality is." s9. The wins people report there share a shape: review against a rule file, translation of a codebase, cleanup of scanned pages.
Managed Agents is a different product. The 70-bug test used Managed Agents dynamic workflows, which are API only. If you build on the API, start with a scoped task, as Anthropic advises s24. Settings for Claude Code do not carry over.
What not to trust. Quota anecdotes without a plan or a number are second-hand. One commenter reports that 6 agents ate a 4-hour quota, and another reports a port of almost 2 billion tokens that cost $20 on a different vendor's cheap model through the commenter's own clone s23 s9. Neither is a measurement of Claude Code on a plan. A number belongs in your notes only when it comes with the plan, the model, the version and the task.
FAQ
Does the keyword cost as much as the toggle? No. The keyword runs one task as a workflow. The toggle plans a workflow for every substantive task, so one request can become several s1. Both spend on top of your conversation, because each agent sends its own requests s5.
Does setting the size guideline to small limit a run to 4 agents? No. It is advice sent to the model, and a prompt or the ultracode sentence can override it s1 s8. On our run it said fewer than 5 and the run used 9. The hard limits are the concurrency variable and your own stop.
What happens when a run hits my usage limit?
With autoContinueAtUsageLimit on, an interactive claude.ai session pauses the run and continues at the reset, up to two waits, from v2.1.271. Earlier versions fail the affected agents s1. With it off, the agents fail at the limit and the run ends there.
Why a cheaper model for the workflow agents?
Most of a workflow is checking, and every agent sends its own requests. CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL puts all workflow agents on one model and leaves your other subagents alone s18. Check the result on a slice before you rely on it.
Can I still use ultracode? Yes, for jobs that pass both questions in the checklist. Bun's port had a full test suite as judge s19. For a small feature or a bug fix, a plain run at high is the default.