Ultracode Is Session-Only, and That Breaks Your settings.json

In You Can't Authorize Autonomy I argued that you don't grant an agent autonomy by flipping a permission flag — you engineer the harness so the autonomy is earned. This is the sequel. Same project, same bypassPermissions setup, one new dial: ultracode.

I wanted ultracode to be my permanent default. So I opened ~/.claude/settings.json and wrote the obvious thing:

{ "effortLevel": "ultracode" }

It silently did nothing. No error, no warning, no behavior change. The setting is just ignored. That single dead line is the whole reason this post exists — because almost everyone reaching for ultracode-by-default will write exactly that and never know it didn't take.

Here's the real answer.

What ultracode actually is

Ultracode is not a model effort level. It's a Claude Code session setting that flips two switches at once:

1. xhigh reasoning — it sends xhigh effort to the model.
2. Orchestrate-by-default — for every substantive task, Claude proactively plans and runs a dynamic multi-agent workflow instead of answering inline. Trivial and conversational turns stay inline.

That second half is the part that matters. xhigh alone gives you a stronger single brain. Ultracode gives you a stronger brain that also spins up a fan-out of subagents by default and converges them on the task.

The effort ladder — and where ultracode sits

There's a linear reasoning ladder, calibrated per model — the same level name maps to a different underlying value on Opus 4.8 vs 4.7 vs Fable 5. An unsupported level silently falls back to the highest one at-or-below it. Default effort is high on Opus 4.8 (xhigh on Opus 4.7).

ultracode is not the top rung of that ladder. It's off the ladder entirely — a different axis. Ultracode sends xhigh to the model (not max) and adds orchestration on top. So in raw single-pass reasoning, max is deeper than what ultracode runs; ultracode wins by parallelism, not by reasoning harder on any one answer.

Two of these — max and ultracode — are session-only in settings.json: the docs are explicit that effortLevel accepts only low/medium/high/xhigh, and max/ultracode are "not accepted here." One exception worth knowing: max (unlike ultracode) can be pinned globally — but only through the CLAUDE_CODE_EFFORT_LEVEL environment variable, which is the single documented way to persist it and takes precedence over settings.json. ultracode has no such escape hatch.

The only three ways to turn ultracode on

1. Per session, standing:

/effort ultracode

Stays on until the session ends or you change it. Revert with /effort high.

2. One task only, no persistence — just say the word in your prompt:

ultracode refactor the auth module and verify the test suite still passes

3. The only non-session route — a launch flag, not a settings line:

claude --settings '{"ultracode": true}'

That's the trick. "ultracode": true works as an inline --settings payload passed at launch (or via an Agent SDK control request), but not inside a settings.json file on disk — there it's silently ignored. Per the official model-config docs, ultracode is passed via --settings or an SDK control request and is not part of the effortLevel setting. The inline flag is the closest thing to a default you can get.

What you do NOT do

Both of these inside a settings.json file are silently ignored. No effect, no feedback. This is the trap:

{ "effortLevel": "ultracode" }
{ "ultracode": true }

The config I first landed on

I run Claude Code in bypassPermissions globally, with a PreToolUse hook that auto-approves every edit (the whole mechanism is in the autonomy post). Today I made three changes to bolt ultracode onto that.

1. Global `~/.claude/settings.json` — the strongest value that actually persists:

{ "effortLevel": "xhigh" }

xhigh is the highest level settings.json will honor. Every project, every SDK call, every non-aliased launch now inherits strong reasoning. This is the floor.

2. My daily-driver alias `c` — baked in true ultracode:

# before
alias c="CLAUDE_CODE_NO_FLICKER=1 claude --permission-mode bypassPermissions --effort max"

# after
alias c="CLAUDE_CODE_NO_FLICKER=1 claude --permission-mode bypassPermissions --settings '{\"ultracode\": true}'"

Now every c launch is true ultracode — xhigh + orchestrate-by-default — on every project. The settings file gives me the persistent floor; the alias gives me the persistent ceiling.

3. Kept the old max-effort launch as `cm` for when ultracode is overkill:

alias cm="CLAUDE_CODE_NO_FLICKER=1 claude --permission-mode bypassPermissions --effort max"

The honest punchline: I wanted "ultracode as the default in settings.json," discovered it's impossible by design, and landed on `xhigh` in `settings.json` + `ultracode` in the launch alias as the real answer.

Update — where I actually landed. I moved my everyday default from ultracode back to max, and split the two into separate aliases:

# where it landed — daily driver is max, ultracode is a deliberate launch
alias c="CLAUDE_CODE_NO_FLICKER=1 claude --permission-mode bypassPermissions --effort max"
alias cx="CLAUDE_CODE_NO_FLICKER=1 claude --permission-mode bypassPermissions --settings '{\"ultracode\": true}'"

So the config section above is what I first tried — this is where it settled. Persisting max also turned out buggier than that section admits. Two things matter.

The shell export only reaches sessions launched from that shell. The desktop app and IDE extensions don't read `~/.zshrc`, so a shell-exported env var never reaches them. The method that works everywhere is the env block in ~/.claude/settings.json, which Claude Code loads on every launch — terminal, app, or IDE:

{
  "env": { "CLAUDE_CODE_EFFORT_LEVEL": "max" }
}

Two open bugs to know. "effortLevel": "max" in settings.json is silently downgraded to high (#65651) — that's why max has to ride the env var. And even when max is active, the effort indicator still reads "extra" (xhigh), a display bug (#52781). The label lies; the only way to see max in the UI today is to run /effort max by hand each session. So I pin max through the env block and ignore the indicator. The trade vs ultracode is still deliberate: max is the deepest single-agent reasoning, ultracode is xhigh + orchestration — depth or fan-out, not both.

The cost reality — read this twice

There is no token ceiling. A workflow converges when the answers stabilize, not when it hits a budget. The only structural caps are: up to 16 concurrent agents (fewer on low-CPU machines) and 1,000 agents total per run. One request can chain multiple workflows — understand → change → verify. Every agent runs your session model (Opus 4.8 by default) at xhigh. And every run counts toward your plan's rate limits — a wide enough workflow can eat your usage window fast.

And here's the gotcha that bites my exact setup. In Auto / bypassPermissions mode with ultracode on, the per-run workflow approval prompt is skipped entirely. Workflow subagents always run in acceptEdits and auto-approve file edits regardless of session mode. So the agents start spending — and editing — with zero gate.

This is precisely the autonomy point. The flag didn't grant judgment; it removed the brake. The discipline has to live in the harness, not the prompt:

• Clean git state first. A dirty tree plus 16 auto-approving agents is how you lose work.
• Pilot on one directory before letting it loose on the repo.
• Watch the `/workflows` token meter. You can stop any time without losing completed work.
• Drop back to `/effort high` the moment you're done.

Two things people conflate

ultracode ≠ xhigh. xhigh is stronger reasoning only. ultracode is xhigh plus orchestration.

ultracode ≠ ultrathink. ultracode is a session setting that changes the API effort and turns on orchestration. ultrathink is a single-prompt keyword that injects a "think harder" instruction without changing API effort at all. Same prefix, completely different mechanism.

One more: don't set disableWorkflows or CLAUDE_CODE_DISABLE_WORKFLOWS. Workflows are on by default on paid plans (Claude Code v2.1.154+); killing them kills ultracode entirely. And you need a model that supports xhigh — Opus 4.7/4.8 or Fable 5.

When to reach for it — and when not

Two questions decide it: is the problem wide, and are you the one orchestrating? Ultracode buys breadth — many agents covering a problem from different angles until the answers stop moving. It does not buy depth; max reasons deeper on any single answer. So reach for it only when breadth is the thing you're short on.

The boundary most people miss: are you the orchestrator, or is something already orchestrating for you? Ultracode's whole trick is making one agent become a swarm. That's exactly what you want when you're driving a single session by hand. It's exactly what you don't want when the agent is a worker inside a harness that already fans out — an unattended loop running parallel workers with an independent second-model review on every merge. There, ultracode nests a swarm inside a swarm: redundant orchestration, far more processes, and it quietly swaps each worker out of max and into xhigh + swarm — the opposite of what you want. I hit this pinning the workers in my autonomy loop — each one should run max, the deepest single-agent reasoning, because the loop is the orchestrator, not the agent. The rule of thumb that falls out: ultracode when you are the harness; max when you have one.

That's why my two aliases split the way they do. c is max — the everyday default, one deep brain. cx is ultracode, reached for deliberately when a problem is wide enough to be worth covering. Spinning up a workflow to fix a typo is just burning the model at xhigh for nothing. Gate the spend yourself — nothing else will.