UltraCode-Shim: Hijacking Claude Code's Premium Mode for Any LLM

Hook

Anthropic's 'UltraCode mode' isn't a special model—it's just three API parameters. This proxy proves it by successfully applying the same envelope to GPT-4, DeepSeek, and even OAuth-based consumer ChatGPT accounts.

Context

Claude Code's autonomous coding workflows are impressive, but they come with a catch: every background task, every parallel sub-agent, every file analysis silently bills against claude-opus-4-8 regardless of what model you selected in the UI. Run a 40-minute refactoring session and you'll rack up hundreds of worker calls you never explicitly authorized. Meanwhile, 'UltraCode mode'—the extended thinking budget and higher token limits—only works with Anthropic's models, locking you into their pricing and quota limits even if you're already paying for GPT-4 or have access to newer models through other channels.

UltraCode-Shim exists because someone got tired of this vendor lock-in and did the reverse-engineering work. The result is a local HTTP proxy that sits between Claude Code CLI and arbitrary LLM backends, transparently wrapping requests with the UltraCode envelope before forwarding them to OpenAI-compatible APIs, OAuth-based services, or even back to Anthropic with modified routing. The architecture proves that premium agentic capabilities aren't gated by secret models—they're envelope-driven. More importantly, it solves the billing problem by intercepting Claude Code's orchestrator/worker split and routing dozens of parallel background tasks to user-chosen (typically cheaper) models based on structural request features.

Technical Insight

The core architecture is deliberately minimal: pure Python stdlib with no external dependencies, using ThreadingHTTPServer for concurrent request handling and SSE streaming with chunked transfer encoding. Configuration lives in a single JSON file that defines model routes—each entry specifies a backend type (openai, anthropic, or codex_oauth), target URL, and whether it handles orchestrator or worker traffic.

Here's what a typical config looks like:

{
  "models": {
    "claude-opus-ultracode": {
      "type": "openai",
      "base_url": "https://api.openai.com/v1",
      "model_id": "gpt-4-turbo",
      "role": "orchestrator",
      "ultracode": {
        "effort": "xhigh",
        "thinking_budget": 10000,
        "max_tokens": 8192
      }
    },
    "claude-sonnet-worker": {
      "type": "openai",
      "base_url": "https://api.deepseek.com",
      "model_id": "deepseek-coder",
      "role": "worker"
    }
  }
}

The orchestrator/worker classification happens through request inspection. The proxy examines the tools array in each request—if it contains AskUserQuestion, EditFile, or other interactive tools, it's an orchestrator turn that should hit your premium model. Requests without those tools are background tasks (file reads, syntax checks, documentation lookups) that get fanned out to the worker model. This is heuristic-based rather than parsing Claude Code's internal metadata, but it's remarkably effective: during a typical autonomous refactoring session, you'll see 1-2 orchestrator calls and 20-30 worker calls, meaning 93% of your requests hit the cheap model.

The retry logic is production-hardened in a way most proxies aren't. Instead of blindly retrying on any error, it buffers the response stream until the first token arrives, then switches to passthrough mode. If the stream is empty after 5 seconds, it retries with exponential backoff—but only for empty turns, so you never get duplicated output. This handles the most common failure mode in long autonomous runs: transient backend hiccups that return 500 errors before any generation starts.

def stream_with_retry(self, request_data, max_retries=3):
    for attempt in range(max_retries):
        buffer = []
        first_token_seen = False
        
        for chunk in self.forward_to_backend(request_data):
            if not first_token_seen:
                buffer.append(chunk)
                if self.contains_content(chunk):
                    first_token_seen = True
                    yield from buffer
                    buffer = []
            else:
                yield chunk
        
        if first_token_seen:
            return  # Success
        
        if attempt < max_retries - 1:
            time.sleep(2 ** attempt)

Tool call translation happens bidirectionally. Anthropic's tool schema uses input_schema with nested JSON Schema objects, while OpenAI expects a flat parameters object. The proxy converts on the fly:

def anthropic_to_openai_tools(self, tools):
    return [{
        "type": "function",
        "function": {
            "name": t["name"],
            "description": t.get("description", ""),
            "parameters": t.get("input_schema", {})
        }
    } for t in tools]

The most clever piece is tool call sequence repair. When users decline a tool mid-conversation (Claude Code asks "Should I modify auth.py?" and you say no), the conversation history contains a tool call with no corresponding result. Strict backends like DeepSeek reject this as malformed. The proxy detects skipped tools by tracking call IDs and synthesizes stub responses:

if tool_call_id in self.declined_tools:
    stub_result = {
        "role": "tool",
        "tool_call_id": tool_call_id,
        "content": json.dumps({"status": "declined", "reason": "User skipped this operation"})
    }
    repaired_messages.append(stub_result)

This keeps the message sequence valid while preserving the semantic meaning of the interaction. The backend sees a completed tool call with a declined result, rather than an orphaned invocation that violates the API contract.

The codex_oauth route type demonstrates sophisticated session management. Instead of requiring API keys, it shells out to codex login for OAuth token refresh, caches credentials in environment variables, and handles ChatGPT Plus or GPT-5.5 access through consumer-tier logins. This means you can point Claude Code at your existing ChatGPT subscription without needing developer API access—a surprisingly practical bridge between consumer and agentic interfaces.

Gotcha

The entire approach is adversarial infrastructure built on vendor ID spoofing. Claude Code's UI filters models by prefix—it only shows options starting with 'claude' or 'anthropic' in the dropdown. To make arbitrary backends appear, the proxy must lie about identity, claiming a DeepSeek model is actually 'claude-sonnet-worker' or similar. This works today because Anthropic's client doesn't validate beyond string matching, but breaks the moment they add signature checks or server-side allowlists. Anyone using this commercially should assume the technique becomes unsupported the instant Anthropic notices it exists.

The orchestrator/worker classification is fragile. It relies on detecting tool names like AskUserQuestion in the request payload—if Claude Code adds new interactive tools or changes its workflow engine to use different primitives, requests will misroute and you'll silently bill the wrong model tier. There's no parsing of Claude Code's internal workflow metadata (because it's not exposed), so the heuristic could degrade over time. More critically, there's zero context window management. The proxy blindly forwards max_tokens values and relies on backends to handle truncation. Switch from Opus (200k context) to a 32k model mid-conversation and you'll hit cryptic errors when the history exceeds limits—no warnings, no graceful degradation, just failed requests. The stdlib-only constraint means no structured logging, no metrics, no token accounting. Debugging a 40-minute workflow that failed at minute 38 means parsing print statements. You can't track actual costs across orchestrator/worker splits without manual log analysis.

Verdict

Use if: You're running long autonomous coding workflows (20+ minutes), need to escape Anthropic's pricing or quota limits without rewriting tooling, and want to A/B test Claude Code's UX against cheaper models before committing to a provider. The orchestrator/worker splitting and production-hardened retry logic are genuinely valuable for multi-hour agentic runs, and the reverse-engineering work proving UltraCode is just parameters saves you from cargo-culting vendor claims about 'special' models. Skip if: You're in a compliance-sensitive environment (the ID spoofing is explicitly adversarial), need observability or token accounting (there's none), require long-term stability (this breaks when Anthropic tightens validation), or want to extend beyond Claude Code (Cursor support is experimental and the architecture doesn't cleanly handle non-HTTP protocols). For production use, LiteLLM proxy offers actual metrics and doesn't require spoofing. For prototyping and hobbyist workflow experimentation, this is the fastest path to real multi-model comparison.