sybil-solutions/codex-shim

codex‑shim – a local routing shim for Codex Desktop

What it is

• A tiny Python + aiohttp server that pretends to be the OpenAI Responses API that Codex Desktop expects.
• It sits on 127.0.0.1:8765 and forwards each request to whichever upstream model you configure – OpenAI, Anthropic, Ollama, Z‑AI, DeepSeek, Gemini, OpenRouter, or even a private ChatGPT‑Codex endpoint.
• The shim translates the upstream response (including streaming Server‑Sent Events, tool calls, image inputs, etc.) back into the exact shape Codex Desktop’s native UI understands, so you keep the full Codex UX while using any “bring‑your‑own‑model” (BYOK) you like.

Why you’d use it

• No rebuild needed – Codex Desktop only shows models that its server advertises. By running codex‑shim you can add arbitrary models to the picker without recompiling Codex.
• Preserves advanced features – function‑call/tool‑output handling, image‑capable models, streaming, and the agent‑loop logic all work unchanged because the shim does a faithful protocol conversion.
• Hybrid setups – you can keep the official ChatGPT Codex model (gpt‑5.5) as a fallback, or route Cursor/Composer agents through a paid subscription without exposing the API key.
• Smart auto‑router (optional) – a cheap classifier can automatically pick the cheapest model that can handle a given request, sending “easy” turns to a small model and “hard” turns to a larger one.
• Proxy‑friendly – the shim’s HTTP endpoint can be wrapped by another local proxy to inject prompts, deduplicate requests, or enforce policy.

How it works

1. Configuration – you create ~/.codex‑shim/models.json (or pass a custom file) that lists models with fields like:

   {
     "model": "gpt‑5.5",
     "provider": "openai",
     "base_url": "https://api.openai.com/v1",
     "api_key": "sk‑…",
     "display_name": "OpenAI GPT‑5.5",
     "max_context_limit": 400000
   }
   

   Supported provider values are openai, anthropic, and a generic OpenAI‑shaped chat API.
2. Generate catalog – codex‑shim generate reads the JSON and writes a Codex‑compatible model catalog (custom_model_catalog.json) plus a small provider block in ~/.codex/config.toml.
3. Start daemon – codex‑shim start launches the aiohttp server on the loopback address.
4. Launch Codex – codex‑shim app . starts Codex Desktop with the shim‑managed block already in its config, so the UI shows all your custom entries.
5. Switch models – codex‑model list / codex‑model <slug> changes the default model by updating the same config block; codex‑app relaunches Codex to apply the change.

Platform support

• Works on macOS, Linux, WSL, Git Bash, and native Windows (PowerShell/cmd). The core server is pure Python, only the optional macOS “picker patch” touches the Electron app.
• Windows Store/MSIX builds have a stricter allow‑list; the shim still functions, but the UI may hide custom slugs unless you use the patch‑free route.

Extra utilities

• codex‑shim patch‑app / restore‑app – apply or revert a one‑line ASAR patch that disables Codex’s hidden‑model filter on macOS.
• codex‑shim opencode‑go refresh – pull a live model list from the OpenCode Go service and merge it into your config.
• codex‑shim generate, list, status, disable – CLI helpers for catalog management and health checks.

Who benefits

• Developers who already use Codex Desktop (the AI‑powered coding assistant) but want to point it at private or cheaper LLM endpoints.
• Teams that need to keep the Codex UI while complying with internal proxy or credential policies.
• Anyone experimenting with multiple providers and wanting a single, locally‑hosted routing layer.

---

TL;DR: codex‑shim is a lightweight Python server that makes Codex Desktop think it’s talking to its built‑in OpenAI endpoint, while actually forwarding requests to any LLM you configure. It lets you add BYOK models, keep all Codex features, and even auto‑route tasks without rebuilding the desktop app.