Skip to main content

Ultracode & Effort Levels: Thinking Depth vs Orchestration

Claude Code's effort levels and per-model defaults, modelSettings and maxEffortLevel, and ultracode, a separate workflow setting: toggling it and limiting runs.

Updated November 4, 2026: Checked against Claude Code v2.1.318. Subagents and teammates on a different model from the main conversation now use that model’s saved or default effort level instead of the session’s (v2.1.317), CLAUDE_CODE_SUBAGENT_EFFORT sets the level for subagents that nothing else assigns one (v2.1.316), and typing ultrathink can run a single turn at xhigh (v2.1.311). The October 21 rewrite for 2.1.305 (the per-model effort matrix, maxEffortLevel, modelSettings, and ultracode as a separate setting since v2.1.284) still applies.

For most of Claude Code’s history, you had one big dial: which model to use. Today there’s a second one, and it might matter more day-to-day. /effort controls how hard the model reasons at each step, and every current Claude model supports it. Ultracode is a separate switch: a Claude Code setting, not another effort level, that tells Claude to orchestrate dynamic workflows for substantive tasks at whatever effort level the session runs at.

This guide covers the five effort levels and which models support them, how Claude Code picks the level, the settings that save and cap it, what ultracode actually changes, the official controls for monitoring and limiting workflow runs, and — just as important — when to leave all of it alone.


What Effort Actually Controls

Effort steers adaptive reasoning: at each step the model decides whether and how much to think, and the effort level sets how readily it does. It doesn’t change which model answers you — that’s /model — it changes how much thinking that model spends before acting.

The trade is straightforward:

more effort  →  deeper reasoning per step
             →  more tokens, more latency
             →  better answers on hard problems

less effort  →  faster, cheaper turns
             →  perfectly fine for mechanical work

Two caveats keep the dial honest. First, the scale is calibrated per model, so the same level name doesn’t mean the same amount of thinking on different models. Second, newer models get more out of each level: “In Anthropic’s testing, Opus 5.5 at medium matches or exceeds Opus 5 at high on coding and knowledge-work evaluations.” When you move from Opus 5 to Opus 5.5, start at medium instead of carrying your old level over.

If you’re also deciding which model to run, read this alongside our model selection guide — model tier and effort level are two separate dials, and the interesting configurations mix them.

The Five Levels

/effort offers five levels: low, medium, high, xhigh, and max. Here’s when to reach for each, following the Claude Code docs:

LevelReach for it when
lowQuick exchanges where you review each result: brainstorming, a first sketch, a rename
mediumThe default on Opus 5.5, Sonnet 5.5, and Haiku 5.5; day-to-day engineering with a clear scope, such as implementing a feature
highWork where verification matters or edge cases are likely, such as fixing a bug in an existing codebase
xhighDeeper reasoning at higher token spend: architecture decisions, adversarial verification, “this must be right”
maxHard problems you want Claude to work through without you, such as hunting for security vulnerabilities

max may show diminishing returns and is prone to overthinking, so test it before adopting it broadly. In Anthropic’s tests on Opus 5.5 and Fable 5.1, higher levels tested more edge cases, verified more of the work, and made more choices on their own; lower levels returned a starting point sooner, which suits work where you review each result and steer the next step.

Which Models Support Which Levels

Claude Code 2.1.318 lists these levels and defaults:

ModelLevelsDefault in Claude Code
Fable 5.1, Fable 5low, medium, high, xhigh, maxhigh
Opus 5.5, Sonnet 5.5, Haiku 5.5low, medium, high, xhigh, maxmedium
Opus 5 (the previous Opus generation), Sonnet 5, Opus 4.8low, medium, high, xhigh, maxhigh
Opus 4.7low, medium, high, xhigh, maxxhigh
Opus 4.6, Sonnet 4.6low, medium, high, maxhigh
Haiku 4.5 and other unlisted modelsNo effort control—

Haiku 5.5 supports effort — it’s the first Haiku-class model with an adjustable effort setting — while Haiku 4.5 is not listed as effort-capable. The distinction matters because haiku still resolves to Haiku 4.5 on Claude Platform on AWS, Amazon Bedrock, Google Cloud’s Agent Platform, and Microsoft Foundry. If you name a level the active model doesn’t support, Claude Code falls back to the highest supported level below it, so xhigh runs as high on Opus 4.6. And Sonnet 5.5 is the one current model whose Claude Code default (medium) differs from its Claude API default (high).

Model visibility and entitlement can differ by provider, plan, account, and rollout; verify what /model shows in your environment.

How Claude Code Picks the Level

Claude Code takes the first of these that applies:

  1. An explicit choice: the CLAUDE_CODE_EFFORT_LEVEL environment variable (which beats the other two), --effort at launch, or /effort in the session.
  2. Your settings: a level saved for the model under modelSettings, or an effortLevel key.
  3. The model’s default: see the table above. On Claude Enterprise, an organization that sets a default effort for its organization default model changes that model’s default.

How long a choice lasts depends on how you make it:

  • /effort high, or Enter in the /effort slider or the /model picker, saves the level as your default for that model, under modelSettings in your user settings.
  • s in the slider or picker (v2.1.257+) applies the level to the current session only.
  • max is session-only unless you set it through CLAUDE_CODE_EFFORT_LEVEL.
  • /effort auto clears your saved level for the active model; /effort status prints the level in effect.
  • In a claude -p run, in the Agent SDK, or from a device connected through Remote Control, the level applies to that session only.
  • ultrathink in a prompt you type affects only that turn. In the interactive terminal (v2.1.311+) and the VS Code extension (v2.1.316+), it can run the turn at xhigh on Opus 5.5, Sonnet 5.5, Haiku 5.5, and Fable 5.1 through Anthropic’s API, and your saved level stays as it was. It is unrelated to the ultracode keyword covered below.

One migration gotcha: a top-level effortLevel in your user settings is the older form /effort wrote before levels became per-model. It still applies to Opus 5, Fable 5.1, and earlier models, but Opus 5.5 and models released after it ignore it and start at their own default until you pick a level for them. (In project, local, or managed settings, a top-level effortLevel applies to every model.)

The session header shows the active level next to the model name (for example, “with low effort”). Changing effort mid-session can also cost you the prompt cache: on most models each level has its own cache, so Claude Code asks you to confirm while the cache is still warm. On Opus 5.5, Sonnet 5.5, Haiku 5.5, and Fable 5.1 with an API key or a Claude subscription, the cache survives the change. Even so, pick your level at the top of a session when you can.

Saving and Capping Effort in Settings

Three settings keys cover effort:

  • effortLevel: a default for models you haven’t saved a level for. It accepts low, medium, high, or xhigh only; not max, and not ultracode.
  • modelSettings (v2.1.251+): per-model entries keyed by model name. Each can hold an effortLevel, a maxEffortLevel cap, and an autoCompactWindow. This is where /effort saves your choice, and a model’s entry beats a top-level effortLevel in the same file.
  • maxEffortLevel (v2.1.267+): a cap. Any higher level runs at the cap instead, whether it came from /effort, --effort, CLAUDE_CODE_EFFORT_LEVEL, a skill’s or subagent’s frontmatter, or the model’s own default. Claude Code enforces it on every provider, including Bedrock, Agent Platform, and Foundry. When several settings files set a cap, the lowest wins, and "max" means no cap. Deploy it in managed settings to enforce it for an organization.

For example, this keeps Opus 5.5 at high instead of its medium default, caps every model at xhigh, and exempts Fable 5.1 from that cap:

{
  "maxEffortLevel": "xhigh",
  "modelSettings": {
    "claude-opus-5-5": { "effortLevel": "high" },
    "claude-fable-5-1": { "maxEffortLevel": "max" }
  }
}

Two more places set effort for a narrower scope. An effort field in a skill’s or subagent’s frontmatter applies while that skill or subagent runs, and since v2.1.292 Claude can pass an effort parameter when it spawns a subagent. Both override the session level but not CLAUDE_CODE_EFFORT_LEVEL, and caps still apply. A subagent with neither runs at the session’s level only when it’s on the main conversation’s model: since v2.1.317, subagents and teammates on a different model use that model’s saved effort level or its default, and the v2.1.316 changelog adds CLAUDE_CODE_SUBAGENT_EFFORT, which sets the level subagents run at when nothing else names one. On Claude Enterprise, admins can also set per-role effort limits for each model; when an organization limit and maxEffortLevel both apply, the lower cap wins.

Ultracode: A Workflow Setting, Not Another Effort Level

Since Claude Code v2.1.284, ultracode is its own toggle. The CHANGELOG puts it in one line: “Changed Ultracode into its own toggle in /effort (Tab, or /effort ultracode [on|off]): it no longer forces xhigh effort and stays on at any effort level.”

So ultracode is a Claude Code setting, not another effort level. With it on, Claude plans a dynamic workflow for each substantive task instead of waiting for you to ask, at whichever effort level the session runs. Claude is instructed to aim for the most exhaustive, correct answer rather than the fastest or cheapest one, and a single request can turn into several workflows in a row: one to understand the code, one to make the change, and one to verify it. That makes every task in the session use more tokens and take longer. On a subscription plan those tokens draw on your usage limits, so you reach a session or weekly limit sooner than you would with ultracode off.

Turning ultracode on also opts you in to large runs, so three checks stand down while it’s on:

  • The Large workflow warning doesn’t appear.
  • The session’s concurrent subagent limit isn’t enforced for subagents Claude spawns with the Agent tool.
  • In auto permission mode, you aren’t asked to approve the first workflow launch.

Ultracode is available only when dynamic workflows are turned on for you and the active model supports xhigh, which rules out models such as Opus 4.6, Sonnet 4.6, and Haiku 4.5. Dynamic workflows are available on all paid plans, with Anthropic API access, and on Bedrock, Agent Platform, and Foundry; on Pro, turn them on from the Dynamic workflows row in /config.

Before v2.1.284 the semantics were different: turning ultracode on set the session to xhigh, picking another level turned it off, and an effort cap below xhigh made it unavailable. If you read older guides (including earlier versions of this one), that’s the behavior they describe.

How to Turn It On and Off

RouteScopeEffect on the effort level
/effort ultracode (or /effort ultracode on)Current sessionUnchanged
/effort ultracode offCurrent sessionUnchanged
Tab in the /effort slider, then EnterCurrent sessionUnchanged
claude --effort ultracodeThe session you launchSet to xhigh
"ultracode": true in a settings file or --settingsEvery session that reads itUnchanged
Agent SDK applyFlagSettings() with effortLevel: "ultracode"That sessionSet to xhigh

The persistent version is a plain settings key:

{
  "ultracode": true
}

Claude Code reads that key but never writes it, because /effort ultracode only affects the current session, and /effort ultracode off turns ultracode off for one session even when the key is true. The persisted effortLevel setting and CLAUDE_CODE_EFFORT_LEVEL don’t accept ultracode; if either of them, or an effort cap, sets the session’s level, ultracode simply stays on at that level. Picking a level in the /effort slider or the /model picker leaves ultracode as it was. The --effort ultracode flag needs v2.1.203 or later; the off form, the slider toggle, and keeping ultracode on at levels other than xhigh need v2.1.284 or later.

The keyword: one task, no session change

To run a single task as a workflow without changing the session’s settings, include the keyword ultracode in your prompt:

ultracode: audit the payments module for correctness bugs

Claude Code highlights the keyword, and Claude writes a workflow script for that task instead of working through it turn by turn. Asking in your own words (“use a workflow to…”) works too. The keyword only chooses how the work is structured: the agents’ tool calls get the same permission checks and sandboxing as any other tool call. It counts only in a prompt you type yourself, so it doesn’t fire from a claude -p prompt, a scheduled task, or a webhook payload or pull-request comment relayed into the session. Press Option+W (macOS) or Alt+W (Windows/Linux) to dismiss a highlight you didn’t mean, or turn the trigger off with Ultracode keyword trigger in /config ("workflowKeywordTriggerEnabled": false).

Workflows also run when you invoke a workflow command, such as the bundled /deep-research or one you saved from an earlier run. Without one of these opt-ins — ultracode, the keyword, an explicit request, or a workflow command — Claude works with individual subagents or on its own. Orchestration at scale is always something you asked for.

Monitoring and Limiting Workflow Runs

Ultracode is an opt-in to more orchestration, not a fixed spend. The official controls are operational:

  • Watch: /workflows lists running and finished runs, and each run’s progress view shows phases, agents, and per-agent token use. Press p to pause or resume, x to stop the selected agent or the whole run, r to restart a running agent, and s to save the script as a reusable command. A one-line progress summary also sits in the task panel below the input box.
  • Warn: a Large workflow warning appears when a run schedules more than 25 agents or its projected token total passes 1.5 million. It’s advisory, and sessions with ultracode on don’t show it.
  • Guide the size: the Dynamic workflow size setting in /config (or the workflowSizeGuideline key) asks Claude to aim for fewer than 5 (small), 10 (medium), or 50 (large) agents, or leaves sizing to Claude (unrestricted). The default is medium, or small on Pro with v2.1.271 or later. It’s advice to Claude, not a cap.
  • Hard limits: the runtime runs up to 16 agents at once by default (fewer on machines with fewer CPUs; CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS accepts 1–256 on v2.1.269+), rejects more than 4,096 items in a single parallel() or pipeline() call, and allows 1,000 agents in total per run.
  • Usage limits: in an interactive session signed in with a claude.ai subscription, an agent that hits your usage limit pauses the run until the limit resets instead of failing (v2.1.271+, with autoContinueAtUsageLimit on).
  • Model cost: workflow agents pick their model in the same order as subagents and otherwise run on your session’s model; CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL (v2.1.296+) puts every workflow agent on one model.
  • Off switches: /effort ultracode off ends the standing opt-in. To remove workflows, and ultracode with them, toggle Dynamic workflows off in /config, set "disableWorkflows": true, or set CLAUDE_CODE_DISABLE_WORKFLOWS=1. An effort cap lowers the level an ultracode session runs at but doesn’t turn ultracode off.

For a costly task, start with one directory or a narrow question, inspect the result and the token use, then expand deliberately.

Per-Agent Effort: Spend Where Judgment Lives

Inside workflow scripts, effort is set per subagent: effort: 'low' | 'medium' | 'high' | 'xhigh' | 'max'. This is where the economics of big runs actually get decided. The pattern:

  • cheap mechanical stages (searching, reading, formatting) → low effort on an effort-capable model, or Haiku without an effort override
  • hard verify/judge stages → high or xhigh

Here’s a bounded discovery loop that puts both ideas together — cheap finders that stop after two dry rounds, then expensive skeptics on whatever was found. (Workflow scripts open with an export const meta = { ... } literal declaring name, description, and phases; the fragment below is the body.)

phase('Discover');

let dryRounds = 0;
const seen = [];

while (dryRounds < 2) {
  const round = await parallel([
    () => agent(
      `Hunt for correctness bugs in the payments module.
       Already seen: ${seen.join('; ') || 'none'}.
       Report only NEW findings, or the word NONE.`,
      { label: 'hunt-correctness', model: 'haiku' }
    ),
    () => agent(
      `Hunt for error-handling gaps in the payments module.
       Already seen: ${seen.join('; ') || 'none'}.
       Report only NEW findings, or the word NONE.`,
      { label: 'hunt-errors', model: 'haiku' }
    ),
  ]);

  const fresh = round.filter(Boolean).filter(r => !r.trim().startsWith('NONE'));
  if (fresh.length === 0) dryRounds += 1;
  else { dryRounds = 0; seen.push(...fresh); }
}

phase('Verify');

const verdicts = await parallel(
  seen.map(finding => () => agent(
    `Try to REFUTE this finding. Confirm only if you cannot:
     ${finding}`,
    { label: 'skeptic', effort: 'xhigh' }
  ))
);

Notice the shape of the spending: the loop that might run many rounds uses Haiku without an effort override, while xhigh is reserved for the verification stage, where a wrong call actually costs you. Leaving effort off the haiku stages is deliberate: haiku means Haiku 5.5 on the Anthropic API but Haiku 4.5 on Bedrock, Agent Platform, Foundry, and Claude Platform on AWS, so the script stays correct on every provider. The finders are told what’s already been seen so they don’t resell old findings, and the loop only stops after two consecutive empty rounds — the “loop-until-dry” pattern covered in depth in the effort and ultracode tutorial and its companion on quality patterns.

When NOT to Use Ultracode

The failure mode of a powerful switch is leaving it on. Skip ultracode for:

  • Trivial edits. A rename, a typo fix, a config tweak needs one agent and low effort. Spawning an orchestrated workflow for it is pure waste.
  • Conversational turns. “What does this function do?” or “which approach do you prefer?” are answered from context. There is nothing to fan out.
  • Single-fact lookups. If you know which file holds the answer, a direct read beats any delegation.
  • Anything where you want fast iteration. Ultracode optimizes for exhaustive and correct, which is the opposite of a quick feedback loop while you’re still sketching.

Rule of thumb: ultracode is for tasks where missing something is expensive and the search space is bigger than one agent’s context. Everything else runs better — and dramatically cheaper — without it. When you return to routine work, run /effort ultracode off. For the broader cost picture, see the cost optimization tutorial.

Three Recipes

The audit. ultracode: audit the auth module for security issues. This is ultracode’s home turf: broad discovery where completeness matters. Start with a bounded scope, use the loop-until-dry shape from the snippet above, adversarially verify every finding, and report any coverage limits explicitly.

The migration. ultracode: migrate every deprecated API call in src/ to the new client. Agents that mutate files in parallel need isolation: 'worktree' on their agent() calls — each gets a fresh git worktree so they can’t trample each other, auto-removed if unchanged. Worktrees cost real setup time and disk per agent, which is exactly the kind of scale you’re consenting to when you type the keyword.

The research sweep. ultracode: map every place we handle currency rounding, and how. A multi-modal sweep — parallel agents each searching a different way (by file location, by content, by entity, by time) — followed by a completeness critic asking “what’s missing?” whose answers seed the next round. Let Haiku sweep without an effort override, and save the expensive treatment for the final synthesis.

The Takeaway

Effort turned answer quality into something you control per task, and in Claude Code 2.1.318 every current model, Haiku 5.5 included, supports the full dial, with medium as the default on the 5.5 family and high on Fable 5.1. modelSettings remembers a level per model, and maxEffortLevel caps it on every provider. Ultracode is a separate setting: it decides whether Claude orchestrates workflows, not how hard each step thinks, and it stays on at whatever level you choose until you run /effort ultracode off. Cost control comes from scope, size guidance, live visibility, the runtime’s agent limits, and the ability to stop a run.

The skill worth building isn’t “always use ultracode” — it’s knowing which of your tasks deserve it. Audits, migrations, and research sweeps, yes. The typo you’re about to fix, no.


Want to go deeper? The Effort Levels & Ultracode tutorial walks through the controls hands-on, and What Is a Workflow? explains the orchestration layer ultracode is built on.