Effort Levels & Ultracode

What You’ll Learn

Session 25 covered which model to run. This session covers the second dial: how hard that model thinks. In the Fable 5 era, Claude Code exposes reasoning effort as a first-class, user-controlled setting — from a quick low-effort pass all the way up to ultracode, a mode where the harness is explicitly told that token cost is not a constraint.

By the end, you’ll understand:

• What /effort controls and what each level trades away
• What ultracode actually is (xhigh effort + dynamic workflow orchestration)
• The two ways to opt in — a keyword in a prompt, or a session-level toggle
• Why ultracode is opt-in rather than automatic
• Token budget directives like +500k and the budget object’s hard-ceiling semantics
• How to set effort per subagent inside a workflow script

The Problem

One model with one fixed thinking depth doesn’t fit real work. Renaming a variable and auditing a payment module are not the same task, but for years the only quality knob you held was model choice. That left two recurring failure modes:

1. Overpaying on trivial work. Deep reasoning applied to a one-line edit is pure waste — slower answers, more tokens, same result.
2. Underthinking the task that mattered. The one migration review that needed exhaustive, adversarial scrutiny got the same effort as everything else, and you found out later.

There was also no honest way to express scale. If you wanted Claude Code to throw dozens of agents at a problem, you had to hope prompt phrasing like “be very thorough” translated into real behavior — and you had no mechanism to say “spend up to this much and no more.” Cost control was aspirational, not enforced. (Session 21’s cost techniques — see /tutorials/s21-cost-optimization — worked around this gap; this era closes it.)

How It Works

The /effort Dial

/effort sets the reasoning effort for the session. There are four levels, plus a special top setting:

/effort
   │
   ├─ low      less reasoning — fast, cheap; mechanical stages
   ├─ medium   the middle of the dial
   ├─ high     hard debugging, verification, judgment calls
   ├─ xhigh    most exhaustive reasoning on demand
   │
   └─ ultracode = xhigh + dynamic workflow orchestration

The trade is what you’d expect: lower effort means faster, cheaper responses; higher effort means more thorough reasoning at more token cost. The guidance that emerges across this era is consistent — cheap, mechanical work gets low effort; verification and judgment get the high tiers.

Like /model, your /effort choice can persist: both commands let you save the selection as a default for new sessions.

Ultracode: xhigh Plus Orchestration

Ultracode is not just another effort level. It is xhigh effort combined with dynamic workflow orchestration. With ultracode on, Claude Code is instructed to:

• Optimize for the most exhaustive, correct answer — not the fastest or cheapest one
• Use multi-agent Workflow orchestration on every substantive task
• Treat token cost as explicitly not a constraint

That last point is the defining property. In normal operation, the harness balances quality against cost. Under ultracode, that balance is deliberately removed: the instruction is to get the right answer, whatever it takes.

Two Ways to Opt In

1. The keyword. Include the word “ultracode” anywhere in a prompt, and that turn runs in ultracode mode. This is a one-off opt-in — the next prompt returns to normal.

> Audit src/payments/ for correctness bugs. ultracode

2. The session toggle. Choose ultracode at the session level (for example, via /effort). This is a standing opt-in: every substantive task in the session gets the full treatment until you turn it off.

Why It’s Opt-In

Ultracode workflows can spawn dozens of agents and consume large token volumes. That scale is exactly the point — but it’s also why the harness refuses to engage it silently. The design principle: the user must explicitly request that scale. No prompt ambiguity, no model deciding on its own to multiply your token spend. You say ultracode, you get ultracode.

Token Budget Directives

The opposite control also exists: instead of removing the cost constraint, you can make it a hard number. Write a directive like +500k in a prompt and the turn gets a token target.

Inside Workflow scripts, that target surfaces as a budget object:

Member	Meaning
budget.total	The target (a number), or null if no directive was given
budget.spent()	Tokens consumed so far
budget.remaining()	Tokens left before the ceiling

Two properties matter:

• The pool is shared. One budget covers the main loop and all workflows in the turn. There’s no per-workflow sub-allowance to game.
• The target is a hard ceiling. Once spent() reaches total, further agent() calls throw. This is not a soft hint the model tries to respect — it’s enforcement at the harness layer. A well-written script checks remaining() before spawning and degrades gracefully; a careless one dies mid-run.

Per-Agent Effort in Workflows

Effort isn’t only a session dial. Workflow scripts can set reasoning effort per subagent:

agent(prompt, { effort: 'low' })    // low | medium | high | xhigh | max

Note that the per-subagent scale goes one step beyond the session dial: it includes a max tier. This is where effort becomes an architectural tool rather than a preference. The pattern:

• Cheap mechanical stages (file reading, searching, formatting, fan-out discovery) → low
• Hard verify / judge / synthesis stages → the high tiers

The same principle applies to model choice (Session 25’s three override points), and the two dials compose: a haiku-class finder at low effort and a top-tier judge at high effort can live in the same script, three lines apart.

Hands-On Example

Here’s the combination in action: a turn opted into ultracode with a hard budget attached —

> Audit src/payments/ for correctness bugs. ultracode +500k

— and a budget-guarded discovery loop, the canonical script shape for “keep looking until findings run dry or the money runs low.” Cheap finders fan out at low effort each round; a reserve is held back so a high-effort synthesis agent can always run at the end.

export const meta = {
  name: 'budget-guarded-audit',
  description: 'Find issues until discovery runs dry or the token budget runs low',
  phases: [{ title: 'Discover' }, { title: 'Synthesize' }],
};

phase('Discover');

const seen = [];   // dedup against everything seen so far
let dryRounds = 0;
let round = 0;

while (dryRounds < 2) {
  round += 1;

  // budget.total is null when the user gave no "+500k"-style directive.
  // Guard BEFORE spawning: once spent() reaches total, agent() throws.
  if (budget.total !== null && budget.remaining() < 60000) {
    log(`Budget guard: ${budget.spent()} spent, ` +
        `${budget.remaining()} left — reserving the rest for synthesis.`);
    break;
  }

  const results = await parallel([
    () => agent(
      `Round ${round}: hunt for correctness bugs in src/payments/. ` +
      `Known findings (do not repeat): ${seen.join('; ') || 'none yet'}. ` +
      `Return one line per NEW finding, or "NONE".`,
      { label: `finder-${round}-bugs`, phase: 'Discover', effort: 'low' }
    ),
    () => agent(
      `Round ${round}: hunt for error-handling gaps in src/payments/. ` +
      `Known findings (do not repeat): ${seen.join('; ') || 'none yet'}. ` +
      `Return one line per NEW finding, or "NONE".`,
      { label: `finder-${round}-errors`, phase: 'Discover', effort: 'low' }
    ),
  ]);

  // parallel() never rejects; a thunk that throws resolves to null.
  const fresh = results
    .filter(Boolean)
    .flatMap((text) => text.split('\n'))
    .filter((line) => line.trim() && line.trim() !== 'NONE');

  if (fresh.length === 0) {
    dryRounds += 1;
  } else {
    dryRounds = 0;
    seen.push(...fresh);
  }

  log(`Round ${round}: ${fresh.length} new, ${budget.spent()} tokens spent.`);
}

phase('Synthesize');

const report = await agent(
  'Verify and write up these audit findings, most severe first:\n' +
  seen.map((f, i) => `${i + 1}. ${f}`).join('\n'),
  { label: 'synthesis', phase: 'Synthesize', effort: 'high' }
);

log(report ? 'Audit complete.' : 'Synthesis agent was skipped.');

Walk through the load-bearing lines:

• The guard runs before each round, not after. Because the ceiling is enforced by throwing from agent(), checking remaining() after spawning is too late. The 60k reserve is the script’s own policy — enough headroom for the synthesis stage.
• The null check matters. With no +500k directive in the prompt, budget.total is null and the loop is bounded only by dry rounds.
• Effort is split by role. Finders are low — they’re breadth, not judgment. Synthesis is high — it’s the one place a wrong call ruins the output.
• Dedup is against everything seen. Each round’s prompt carries prior findings so finders don’t resurface duplicates forever.
• .filter(Boolean) handles both failure shapes: parallel() converts thrown thunks to null, and agent() itself returns null if the user skips an agent or it dies on a terminal API error.

The full Workflow API behind this script — meta, phase(), pipeline() vs parallel(), resume semantics — is Session 27’s subject.

What Changed

Before	Fable 5 Era
Quality knob = model choice only	Two independent dials: model × effort
”Please think hard” prompt begging	/effort levels: low / medium / high / xhigh
Thoroughness at scale: unpredictable	Ultracode: xhigh + workflow orchestration, by contract
Big spends could happen implicitly	Scale requires explicit opt-in (keyword or toggle)
Cost control: watch the meter and hope	+500k → hard ceiling; agent() throws at the limit
One effort for the whole session	Per-subagent effort in workflow scripts (up to max)

Key Insight

Quality-versus-cost became a user-held dial, not a model constant.

Every piece of this session is the same idea from a different angle. /effort separates “which model” from “how hard it works.” Ultracode is the dial pinned to maximum — with the harness contractually ignoring cost. The +500k directive is the dial pointed at a number — with the harness contractually refusing to exceed it. And per-agent effort pushes the dial down into individual workflow stages.

Notice where the guarantees live. Ultracode’s exhaustiveness and the budget’s ceiling are both enforced by the harness — an agent() call that throws at the limit is structural, like a hook blocking a tool call, not behavioral, like an instruction the model tries to remember. That’s the era’s signature move: promises about effort and cost moved out of the prompt and into the machinery.

Spend the dial deliberately: low effort for the mechanical 90% of work, high tiers where a wrong judgment is expensive, ultracode when correctness genuinely outranks cost — and a budget directive whenever you want that trade capped in writing.

Next Session

Session 27 opens up the machinery this session kept gesturing at: the Workflow tool — Claude Code’s scripted multi-agent orchestration, where control flow lives in deterministic JavaScript and judgment lives in models. See /tutorials/s27-workflow-orchestration.