A localhost shim that smuggles BYOK models into Codex Desktop

What it does

codex-shim is a local Python/aiohttp server that pretends to be OpenAI’s Responses API on loopback. Codex Desktop points at it blindly; the shim forwards each request to the real upstream—Anthropic, DeepSeek, OpenRouter, a generic chat endpoint, or your ChatGPT subscription’s Codex backend—then rewrites the streaming response into whatever shape Codex expects. You declare models in a JSON file, and they show up as normal picker entries, preserving agent loops, function calls, reasoning blocks, and image support without rebuilding the client.

The interesting bit

The heavy lifting is protocol translation, not just proxying. Codex speaks a specific OpenAI dialect that most providers lack, so the shim has to massage SSE streams, tool outputs, shell metadata, and reasoning blocks in real time to keep the native agent loop from breaking. It also offers an optional auto-router that classifies each task and dispatches trivial turns to a cheap model while escalating hard ones, plus a passthrough that borrows your existing ChatGPT gpt-5.5 token so you don’t need a separate API key.

Key highlights

• BYOK models appear as first-class entries in Codex Desktop’s picker—no source rebuild or request-replay hacks.
• Translates between OpenAI Responses API and upstream formats (Anthropic Messages, generic OpenAI chat, etc.) while keeping streaming, tool use, and multimodal support intact.
• Optional ChatGPT/Codex passthrough uses the token already in ~/.codex/auth.json to reach the subscription gpt-5.5 backend.
• Optional Cursor/Composer passthrough and an Auto (smart routing) classifier that routes each turn to the cheapest capable configured model.
• Runs locally on loopback; the maintainer notes internal cost and latency improvements when pairing the shim with a prompt-catching proxy, though no reproducible benchmarks ship yet.

Caveats

• The optional Desktop picker patch is macOS-only; Windows Store/MSIX builds may ignore custom slugs and force the model back to gpt-5.5 due to Desktop allowlist behavior.
• The maintainer’s reported multi-x token savings and faster wall time are explicitly labeled anecdata—no benchmark script is included.
• Compatibility is verified only against Codex Desktop 0.133.0-alpha.1 on macOS arm64; newer or other builds are untested.

Verdict

Worth grabbing if you want Codex Desktop’s agent UX but need to route through your own Anthropic, DeepSeek, or local proxy keys. If you are content with OpenAI’s default hosted Codex and its model list, the extra localhost indirection buys you nothing.