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

Windows

git clone https://github.com/OnlyTerp/UltraCode-Shim.git
cd UltraCode-Shim

# 1. Sanity-check your machine and config (safe to run anytime)
python scripts\doctor.py

# 2. Tell it which models you want (see "Configure your models" below)
#    Copy config.example.json to config.json, keep the models you have,
#    and put your keys in it (config.json is gitignored).
copy config.example.json config.json

# 3. Create Desktop icons (one for UltraCode, one for normal Claude Code)
.\windows\Install-DesktopIcons.ps1

# 4. Double-click "UltraCode (All Models)" — pick orchestrator + worker in the selector.
#    You can still type /model later to change either tier.

macOS / Linux / WSL

Run python3 scripts/doctor.py then ./bin/ultracode. The launcher starts the proxy, opens the two-column orchestrator/worker selector, then launches Claude Code. Set UC_SELECTOR=0 to skip the selector and use /model only. (The launchers copy config.example.json → config.json for you on first run if you skip step 2.)

Configure your models

Everything is in one file: config.json (copied from config.example.json). It has two sections you edit:

• models — what shows up in the /model menu. Every id must start with claude or anthropic (Claude Code filters the rest out).
• routes — where each of those ids actually goes. The route key must match the model id.

Example — MiMo and an OpenRouter model:

{
  "models": [
    { "id": "claude-mimo",       "display_name": "MiMo v2.5 Pro" },
    { "id": "claude-openrouter", "display_name": "Llama 3.3 70B (OpenRouter)" }
  ],
  "routes": {
    "claude-mimo": {
      "type": "openai_compat",
      "upstream": "https://token-plan-sgp.xiaomimimo.com/v1",
      "model": "mimo-v2.5-pro",
      "auth": "Bearer ${MIMO_API_KEY}"
    },
    "claude-openrouter": {
      "type": "openai_compat",
      "upstream": "https://openrouter.ai/api/v1",
      "model": "meta-llama/llama-3.3-70b-instruct",
      "auth": "Bearer ${OPENROUTER_API_KEY}"
    }
  }
}

Put your key right in config.json (it's gitignored) or use ${ENV_VAR} and export it — or drop keys into a gitignored ultracode.env the launchers load.

Route types:

type	Use for	Needs
(omit)	Real Claude or any Anthropic-compatible endpoint	nothing, or auth/upstream
openai_compat	MiMo, DeepSeek, OpenRouter, OpenAI, Ollama, local llama.cpp — anything that speaks OpenAI Chat Completions (tools included)	an API key
codex_oauth	GPT‑5.5 via a ChatGPT/Codex login (no API key)	codex login once
cursor_agent	Cursor Composer (experimental)	cursor-agent login
auto	The Auto Router — score candidates per task and route to the cheapest that's good enough	a router block + a classifier model

Reasoning models (MiniMax‑M3, etc.): an openai_compat route can carry a "body": { ... } dict of extra params merged into every request. MiniMax‑M3 needs "body": { "reasoning_split": true } so its <think> chain‑of‑thought is returned separately instead of leaking into the visible answer — the shipped example already sets this. See docs/ADD_A_MODEL.md.

Full walkthrough: docs/ADD_A_MODEL.md.

Is my normal Claude Code safe?

Yes. The UltraCode launcher only sets environment variables for the launched process and uses a session-scoped --settings file. It never edits your global Claude config or credentials. The installer also gives you a "Claude Code (Normal)" icon, so you can always start the plain version. Remove everything with windows\Uninstall.ps1.

Telling your AI assistant to set this up

This repo is built so you can hand it to an assistant. Point it at AGENTS.md — that's a step-by-step runbook (install → configure → test → troubleshoot) written for an AI to follow.

Docs

Doc	What
AGENTS.md	Runbook for an AI assistant to install/configure/test
docs/SETUP.md	Human setup guide (Windows + macOS/Linux)
docs/HOW_IT_WORKS.md	The mechanism + reverse-engineering evidence
docs/AUTO_ROUTER.md	The Auto Router — pick the right model per task automatically
docs/ADD_A_MODEL.md	Add any backend to the /model menu
docs/TROUBLESHOOTING.md	Symptom → cause → fix

License

MIT — see LICENSE. This is an unofficial, community project; it is not affiliated with Anthropic, OpenAI, or any model provider. You are responsible for complying with the terms of whatever accounts you route through it.