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, DeepSeek, Gemini, OpenRouter, local Ollama servers, or even the official ChatGPT Codex endpoint.
• The shim translates request/response shapes (including streaming SSE, tool calls, image inputs, etc.) so Codex Desktop can keep its native UI and agent loops unchanged.

Why you’d use it

• Bring your own models (BYOK) into Codex Desktop without rebuilding the app. Just drop a JSON file describing the models and the shim makes them appear in the picker.
• Keep Codex’s UX – function‑calling, reasoning blocks, image handling, and streaming work exactly as they do with the built‑in model.
• Optional ChatGPT passthrough – if you have a valid Codex access token, the shim can forward /v1/responses to the official ChatGPT Codex backend under the gpt‑5.5 slug.
• Cursor integration – when you are logged into Cursor, the shim can expose the composer‑2‑5 model without needing a separate Dashboard API key.
• Smart auto‑router (optional) – a cheap classifier can automatically pick the cheapest model that can handle a given task.
• Proxy‑friendly – you can place another local proxy in front of the shim to inject instructions, deduplicate prompts, or enforce policies.

How it works

1. Configuration – you create ~/.codex‑shim/models.json (or pass a custom file with --settings). Each entry lists:
   • model / slug
   • provider (openai, anthropic, generic-chat-completion-api, etc.)
   • base_url and authentication (api_key or api_key_env)
   • optional UI hints like display_name, max_context_limit, no_image_support.
2. Generate catalog – codex‑shim generate reads the JSON and writes a Codex‑compatible catalog (custom_model_catalog.json) and a provider config (config.toml).
3. Run the shim – codex‑shim start launches the aiohttp daemon listening on the loopback address.
4. Tell Codex Desktop to use it – codex‑shim app . launches Codex Desktop with the local provider injected into ~/.codex/config.toml. The app now sees every model you listed, plus the optional gpt‑5.5 passthrough if you have a token.
5. Switch models – codex‑model list shows the slugs; codex‑model <slug> selects one, and codex‑app relaunches Codex.

Supported upstreams

Provider	Upstream endpoint
openai	OpenAI /v1/chat/completions
generic-chat-completion-api	Any OpenAI‑shaped chat endpoint
anthropic	Anthropic /v1/messages
ollama (via generic)	Local Ollama /v1/chat/completions
opencode‑go (refresh command)	OpenCode Go catalog API

The shim can also accept Anthropic‑style Messages requests on its own endpoint and translate them to the appropriate shape for the upstream.

Key commands

• codex‑shim generate – build the catalog from your model list.
• codex‑shim start – launch the local server.
• codex‑shim status – health check and model count.
• codex‑shim list – show which slugs map to which upstreams.
• codex‑shim app – start Codex Desktop with the shim wired in.
• codex‑shim model use <slug> – pick a model for the next session.
• codex‑shim disable – remove the shim‑managed block from Codex’s config.
• codex‑shim patch‑app / restore‑app – macOS‑only ASAR patch that forces Codex Desktop’s picker to show custom slugs (required on macOS because the official app hides unknown models).
• codex‑shim opencode‑go refresh – pull the latest OpenCode Go model list automatically.

Installation

git clone https://github.com/0xSero/codex-shim ~/codex-shim
cd ~/codex-shim
python3 -m pip install --user -e .   # installs the `codex-shim` CLI

(Windows users can run the same steps with py -3.11.)

Platform support

• Works on macOS, Linux, WSL, Git Bash, and native Windows PowerShell/cmd.
• The core shim is pure Python; only the optional macOS picker patch needs npx and codesign.
• Windows Store/MSIX builds of Codex may hide custom slugs, but the shim’s routing still works; the UI will only show the built‑in model.

Typical workflow

# 1. Describe your models
cat ~/.codex-shim/models.json   # (see README for schema)

# 2. Build the catalog and start the shim
codex-shim generate && codex-shim start

# 3. Launch Codex Desktop through the shim
codex-shim app .

# 4. Pick a model from the dropdown (or via CLI)
codex-model list
codex-model gpt-5.5
codex-app   # relaunch to apply the new default

What you get

• All of Codex Desktop’s advanced features (function calls, tool output, image support, streaming) remain functional.
• You can route to cheap local models (e.g., Ollama) for simple tasks and automatically fall back to a more powerful cloud model for harder ones.
• No need to rebuild or re‑sign Codex Desktop (except the optional macOS picker patch).

---

Bottom line: codex‑shim is a practical bridge that lets the commercial Codex Desktop coding‑assistant use any OpenAI‑compatible, Anthropic, or locally hosted LLM you like, while preserving the app’s native experience. It’s a pure‑Python, cross‑platform shim rather than a new model or training framework.