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 settings here are session-only: max and ultracode. The official docs are explicit — effortLevel accepts only low/medium/high/xhigh. max and ultracode are "not accepted here." Put either in a settings file and it's ignored.

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 that actually sticks — my real setup

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.

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 it's worth it vs overkill

Worth it: a multi-file feature, a gnarly bug whose cause you can't localize, a refactor that has to land and stay green, anything where you want the full understand→change→verify loop run exhaustively. That's c.

Overkill: a rename, a one-liner, a "what does this function do," a quick config tweak. Sixteen subagents to fix a typo is just burning Opus at xhigh for nothing. That's cm, or plain high.

The reason ultracode helps isn't that it makes the model smarter on any single answer — max already reasons deeper in one pass. It helps because it changes the shape of the work: many agents attacking the problem from different angles, converging until the answers stop moving. You're buying exhaustiveness, not a smarter single answer. Pay for it when the problem is wide enough to be worth covering — and gate it yourself, because the harness won't.