Ultracode: Reasoning, Workflows and the Config That Persists

Ultracode is a Claude Code orchestration setting: it combines xhigh model effort with automatic dynamic workflows for substantive tasks. It is useful when a problem can benefit from parallel investigation and a deliberate integration stage.

This article has been updated against the September 20, 2026 documentation. The earlier claim that ultracode could never persist in settings.json is obsolete. Current versions support a dedicated ultracode key.

The configuration that persists

{ "ultracode": true }

Use that key in a supported settings file. For one session, run /effort ultracode or launch with the flag below; --effort ultracode requires version 2.1.203 or later. Do not put ultracode in the persisted effortLevel key or CLAUDE_CODE_EFFORT_LEVEL: those are different controls.

claude --effort ultracode

An environment effort override other than xhigh keeps ultracode orchestration inactive. A disabled workflow feature, an unsupported model, or an organization effort cap can also prevent activation. Check the effective session state rather than assuming a saved line was honored.

Reasoning and orchestration are different choices

Max is the deepest named reasoning level; ultracode selects xhigh plus orchestration. Neither label establishes which configuration produces the best accepted result on a particular task. A difficult localized bug may benefit from a sustained investigation. A migration spanning independent modules may benefit from several bounded workers.

An outer controller that already delegates work should make this choice explicitly. Nested orchestration can duplicate exploration and complicate resource accounting. That is a design tradeoff, not a reason to ban workflows: assign one component responsibility for the overall plan and the final acceptance check.

What a workflow actually controls

Claude writes JavaScript orchestration that coordinates agents. The default concurrency is up to 16, with lower defaults on constrained machines; version 2.1.269 and later can configure 1–256. The documented total remains 1,000 agents per run. These are runtime bounds, not evidence that every request needs hundreds of agents.

Keyword activation is limited to human-origin input in current versions. A relayed webhook, scheduled prompt or ordinary headless -p argument does not gain that trigger merely by containing the word ultracode. Headless workflows instead need the supported tool and permission path.

Permissions do not disappear

Approval behavior depends on the interface and permission mode. Auto mode with ultracode can skip a per-run confirmation, while headless execution evaluates the Workflow call through its permission machinery. Subagent access follows the applicable rules; do not assume every child receives unrestricted edits.

Before a broad run, define which files each worker owns, which tests establish completion, and where integration happens. Preserve concurrent edits. A passing test suite is evidence about tested behavior, not permission to merge unrelated changes.

A practical evaluation

Compare two approaches on the same recoverable task: one worker with a clear investigation plan, and a workflow with bounded independent tasks. Record whether the patch passes review, how many defects remain, wall time and actual usage. Keep the model and acceptance criteria visible so an apparent orchestration win is not just a changed experiment.

For a workflow, require a final integration report that names the changed files and the evidence for acceptance. Reviewers should be able to trace a conclusion to a test, a source or a concrete diff. More agents are useful only when they produce a better result than the coordination work they add.

Sources: Effort and configuration; Dynamic workflows. Documentation checked September 20, 2026.