UltraCode-Shim

Use Claude Code's UltraCode mode (xhigh effort + the Workflow/deep-reasoning harness) with any model you already pay for — pick it live from the /model menu.

One icon. Open Claude Code, type /model, and choose any backend you've set up — all running with the full UltraCode harness. Your normal Claude Code install is left untouched.

The example config ships ready-to-use entries for GPT‑5.5 (Codex login), MiniMax‑M3, MiMo v2.5 Pro, DeepSeek V4 Pro/Flash, Step Flash, Ollama Cloud, OpenCode Go, OpenRouter, and local models — keep the ones you have a plan for, delete the rest. (Cursor's Composer needs the cursor-agent CLI and isn't HTTP-based — see docs/ADD_A_MODEL.md.)

How it works

How is this possible? At the API level, "UltraCode" is just effort=xhigh + adaptive thinking + a big max_tokens + one system reminder — there is no secret model. The proxy adds that envelope to every request, so any backend gets the UltraCode treatment. Full breakdown (with the reverse‑engineering evidence) in docs/HOW_IT_WORKS.md.

Orchestrator + Worker: two models, one workflow 🪄

Claude Code's /model menu is single-slot — and its dynamic-workflow engine quietly issues most of its background/sub-agent traffic as the stock model (claude-opus-4-8) no matter what you pick. So the dozens of parallel workers that do the bulk of a workflow don't follow your selection (and can bill a model you didn't choose).

This proxy turns that single slot into two. The launcher opens a two-column selector before Claude Code starts: choose an orchestrator (the main interactive loop) on the left and a worker (every Workflow/Task sub-agent) on the right. The same choices are also available later in /model: for every model you configure, the proxy auto-adds a Worker → <model> entry.

• Pick one model (or choose Same as orchestrator in the selector) → it runs everything, orchestrator and every parallel worker. One pick, your model end-to-end.
• Pick an orchestrator plus a worker model → the smart model plans while a cheaper/faster model fans out the parallel work.

How it routes: the proxy classifies each request by a structural signal (the main loop carries interactive-only tools like AskUserQuestion; sub-agents never do), then sends the orchestrator tier to your orchestrator model and every worker to your worker model. The workflow's stock-model background calls are remapped to your picks too — so "use MiniMax" really means MiniMax everywhere, not Opus behind the scenes. Toggle off with UC_ORCH_WORKER=0. Workers run fully in parallel (threaded proxy, no artificial concurrency cap).

Auto Router: the right model for every task, automatically 🧭

Don't want to pick at all? Choose Auto (smart routing) and the proxy decides per task which of your backends to use — trivial turns go to a cheap model, hard turns escalate to your strongest one. Same idea as Factory Droid's model router ("frontier quality, lower cost"), rebuilt on the models you already pay for.

A tiny, cheap classifier model you nominate scores each candidate 0–1 on how likely it is to nail the current task (reading a short capability card you write for each). The proxy then routes to the cheapest candidate that clears a quality bar (default 0.7). The classifier never sees price, so it can't be biased toward expensive models; decisions are cached per task; and it degrades safely (any failure falls back to a sensible default and never breaks a request). It's off until you configure it — the shipped config.example.json has a ready-to-use block. Full guide: docs/AUTO_ROUTER.md.

"router": {
  "enabled": true,
  "classifier": "claude-mimo",        // your cheapest fast model does the scoring
  "threshold": 0.7,                   // cheapest candidate scoring >= this wins
  "candidates": [
    { "id": "claude-minimax-m3",    "cost": 0.3, "card": "cheap; single-file edits, codegen, simple refactors" },
    { "id": "claude-gpt-5.5-codex", "cost": 5.0, "card": "frontier; big refactors, hard debugging, images" }
  ]
}

Works as your orchestrator, your worker, or both. Watch it decide with UC_ROUTER_LOG=1.

See it route, offline (no keys):

python3 examples/auto_router_demo.py

#  Task                                         Classifier scores                Routed to      Cost
1  add a docstring to the foo() helper          cheap=0.90 mid=0.92 strong=0.95  claude-cheap   $0.3
2  write a CRUD REST endpoint with tests        cheap=0.50 mid=0.85 strong=0.95  claude-mid     $1.0
3  refactor the auth module across 8 files ...  cheap=0.40 mid=0.55 strong=0.95  claude-strong  $5.0
4  what does this screenshot show?  [image]     cheap=0.90 mid=0.92 strong=0.95  claude-strong  $5.0  ← only vision-capable
5  (repeat task #1)                             served from cache                claude-cheap   $0.3  ← classifier not re-called

Built for long, dynamic workflows ✨

UltraCode shines on long, autonomous runs — deep reasoning, multi-step Workflows, multi-agent fan-out. The catch with any "route to a third-party backend" shim is that those backends occasionally hiccup, and on a 40-minute agent run a single unhandled hiccup can wedge the whole session. We hardened the proxy against the three failure modes we actually hit in production, so it keeps going instead of stalling:

• 🔁 Empty turns auto-retry. A backend that returns a turn with no text and no tool call (a transient blip, or a budget-exhausted reasoning turn at high effort) is transparently re-issued. It buffers only until the first real token, so a normal turn adds zero latency and output is never duplicated — and it never retries after real output or a fatal error.
• ⏱️ A stalled stream can't freeze the run. If a GPT‑5.5/codex stream opens and then goes silent mid-turn, a bounded idle timeout turns the stall into a quick retry instead of a ~10-minute hang — so one stuck sub-agent no longer freezes an entire multi-agent / dynamic-workflow run.
• 🛠️ Rejecting a tool call just works. Declining (or skipping) a tool mid-run no longer 400s strict backends like DeepSeek — the proxy repairs the tool-call sequence and synthesizes a stub reply for anything you didn't answer, including partial parallel calls. (#3)
• 💬 No "dead air" while a model thinks. Reasoning models (MiniMax‑M3, etc.) can think for seconds before the first answer token. The proxy keeps the connection live during that phase, so a workflow step looks busy instead of frozen — without leaking the chain-of-thought into the answer.

All of these are tunable via env vars and locked down by the offline self-test in CI. Details and knobs: docs/HOW_IT_WORKS.md → Reliability.

Demo

There's a ready-to-run scenario in examples/demo/ — a buggy little Game of Life. Launch UltraCode there, pick any model, enable auto mode, and paste the prompt: it fixes the bug, adds an animated color renderer + starting patterns, and runs its own self-test, ending on a glider crawling across the screen.

Verified live against real backends: GPT‑5.5 (Codex login) and Cursor Composer, plus an offline self-test that runs in CI on Linux/Windows × Python 3.8/3.12.

What you need

• Claude Code CLI with UltraCode access (npm i -g @anthropic-ai/claude-code).
• Python 3.8+ (standard library only — there is nothing to pip install).
• At least one backend credential, e.g. an API key (MiMo / OpenRouter / OpenAI / a local server) and/or a codex login for GPT‑5.5. You only set up the ones you have.

Tested on Windows 11 (no WSL needed). macOS/Linux/WSL work too via bin/ultracode.

Quick start

One command gets the code, runs the offline self-test, creates your config.json, and installs a ultracode launcher on your PATH. Then you edit one file and run ultracode.

macOS / Linux / WSL

curl -fsSL https://raw.githubusercontent.com/OnlyTerp/UltraCode-Shim/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/OnlyTerp/UltraCode-Shim/main/install.ps1 | iex

Already cloned the repo? Just run ./install.sh (or .\install.ps1) from inside it — same result, no network clone.

Then:

1. Pick your models — edit config.json (created for you): keep the backends you have a key/plan for, delete the rest, drop your keys in. See Configure your models.
2. Run it — ultracode. The launcher starts the proxy, opens the two-column orchestrator/worker selector, then launches Claude Code. Type /model anytime to change either tier. (UC_SELECTOR=0 skips the selector and uses /model only.)

Prefer Desktop icons on Windows? Run .\install.ps1 -DesktopIcons (or, in a clone, .\windows\Install-DesktopIcons.ps1) to get "UltraCode (All Models)" and "Claude Code (Normal)" shortcuts. Uninstall the launcher anytime with ./install.sh --uninstall (or .\install.ps1 -Uninstall).

git clone https://github.com/OnlyTerp/UltraCode-Shim.git
cd UltraCode-Shim
python3 scripts/doctor.py                 # sanity-check + offline self-test
cp config.example.json config.json        # then edit it (gitignored)
./bin/ultracode                           # mac/linux/WSL
#   windows: .\windows\Start-UltraCode.ps1   (or .\windows\Install-DesktopIcons.ps1)

The launchers copy config.example.json → config.json for you on first run if you skip that step.

Configure your m