codex-shim: a local Responses API proxy that puts BYOK models in the Codex Desktop picker

What codex-shim is for

Codex Desktop only shows models allowed by its server side config. If you hold keys for OpenAI, Anthropic, Z.ai, DeepSeek, Gemini, OpenRouter or a local proxy and you want those as first class picker entries, there is no supported way to add them from the app. codex-shim is a local Python and aiohttp server that exposes an OpenAI Responses compatible endpoint on loopback; Codex points at the shim, and the shim routes each request to the upstream you configured. The practical win is that Codex keeps its native user interface while model routing moves to your machine. It is aimed at people who already pay for model access somewhere else and do not want to give up the Codex agent loop to use it. Python 3.11 or newer and an authenticated Codex CLI or Desktop install are the stated requirements.

How the routing works

The shim accepts a request in the Responses API shape, decides which upstream it maps to, and translates in both directions. Four upstream kinds are listed: OpenAI chat completions, Anthropic Messages, a generic OpenAI shaped chat endpoint, and a ChatGPT Codex passthrough. Translation is the part that decides whether this is usable, and the README is specific about what survives it. Function calls, tool outputs, reasoning blocks, image capable models, shell command metadata and streaming SSE are translated rather than flattened into plain text, so the Codex agent loop keeps working against models it was never shipped with. Configuration lives in ~/.codex-shim/models.json, or in a compatible JSON file passed with --settings. The shim writes the same Codex provider config that macOS and Linux use, and on Windows that means %USERPROFILE%/.codex/config.toml.

Installing codex-shim and getting a first request through

On macOS, Linux, WSL or Git Bash the recommended path installs the console entry point declared in pyproject.toml, which pulls in aiohttp and gives you the codex-shim command.

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

Two optional shortcuts live in bin/ as shell scripts. Symlink them if you want them on PATH, and remember that moving the checkout means recreating the links, since codex-shim app launches codex app through the installed entry point and does not need them.

mkdir -p ~/.local/bin
ln -sf "$PWD/bin/codex-app" ~/.local/bin/codex-app
ln -sf "$PWD/bin/codex-model" ~/.local/bin/codex-model

If your shell cannot find the command, the README says to make sure the local bin directory is on PATH.

export PATH="$HOME/.local/bin:$PATH"

On native Windows PowerShell or cmd, install with the Python launcher and drive it through the entry point rather than the shell wrappers.

py -3.11 -m pip install --user -e .
codex-shim generate
codex-shim start
codex-shim status
codex-shim list

If the command is still not on Path, the README gives the module form, py -3.11 -m codex_shim.cli status, which sidesteps the scripts directory entirely. The tests run with pytest and pytest-asyncio.

Windows, WSL and macOS: what differs

The support table is worth reading before you plan a setup. Native Windows PowerShell and cmd are supported: install with py -3.11 -m pip install --user -e . and run codex-shim subcommands. WSL works like Linux and is the better choice when Codex CLI or Desktop is also driven from WSL. Git Bash works with the POSIX bin wrappers provided Python and Codex are on PATH. The bin/codex-app and bin/codex-model wrappers are shell scripts and are not native to PowerShell or cmd, so the README tells you to use codex-shim app and codex-shim model there instead. The patch-app and restore-app commands are macOS only because they target /Applications/Codex.app and Electron ASAR signing. Path behaviour follows the platform: on Windows the models file resolves under %USERPROFILE%/.codex-shim/ and the Codex config under %USERPROFILE%/.codex/.

The optional extras

Three features sit behind the basic routing. Auto Router adds an Auto (smart routing) picker entry that uses a cheap classifier model to send each task to the cheapest configured model that can handle it, so trivial turns stay cheap and hard turns escalate. A ChatGPT Codex passthrough routes Codex native /v1/responses traffic to the ChatGPT Codex backend under the gpt-5.5 slug used by current Codex builds, but only when ~/.codex/auth.json holds a valid Codex access token. A Cursor Composer passthrough exposes composer-2-5 through an active cursor-agent login without a Dashboard API key. The README also describes a prompt catching and proxy friendly architecture, where you put your own local proxy in front of the shim to dedupe boilerplate, inject stable instructions, repair pseudo tool text or route prompts by policy before they reach an upstream.

Where it can disappoint

Start with the version boundary. The README states the shim was tested on Codex Desktop 0.133.0-alpha.1 for macOS arm64, and while the server and routing layer are plain Python and aiohttp that run anywhere, that is the only build the maintainer claims to have exercised. The picker is the fragile part: when Codex hides custom catalog entries, the optional Desktop picker ASAR patch is needed, and that is macOS only and requires npx and codesign. On performance claims, be careful. The README reports multi fold reductions in billed input tokens and faster wall time on the maintainer internal tasks with ChatGPT passthrough and a prompt catching proxy, then states plainly that no reproducible benchmark script ships with the repository and that you should treat it as anecdote and measure your own setup against an explicit oracle before quoting numbers. That is honest, but it means there is no published measurement to plan capacity against.

The alternative: hand written provider config

You can edit ~/.codex/config.toml yourself and point Codex at an OpenAI compatible endpoint. That route has no Python dependency, no local server to keep running and nothing to start before a session, and it is enough when your provider genuinely speaks the Responses API and you drive Codex from the CLI where the model is named in config rather than picked from a list. It fails in two places the shim covers. First, Codex Desktop only shows models allowed by its server side config, so an entry you add by hand can stay invisible in the picker, which is exactly the gap the macOS ASAR patch exists to close. Second, a raw config entry does no translation: an Anthropic Messages endpoint or a generic chat endpoint returns shapes Codex does not parse, and there is no layer turning tool calls, reasoning blocks and streaming SSE into the form Codex expects. Choose the plain config if one provider already matches; choose the shim when you are mixing providers or need the picker.

Upkeep and licence

The project is MIT licensed and its last push was on 2026-08-25. The runtime dependency footprint is deliberately small: aiohttp is the single required package, with pytest and pytest-asyncio behind a dev extra, so a Python upgrade is unlikely to break much beyond that. The maintenance surface you own is the models file, and since it is plain JSON in your home directory it is easy to version and restore. What you are really taking on is coupling to an unreleased Codex Desktop build, because the shim depends on the config layout and the Responses shape that build expects. If Codex later exposes custom providers natively, the reason to run a local proxy disappears, and the picker patch is the piece most likely to break on a Codex update.

Editorial conclusion

Take codex-shim if you hold API keys for providers Codex Desktop will not list and you want them in the native picker with tool calls and reasoning intact rather than flattened into text. Skip it if you are happy with the models Codex already offers, or if you need the picker patch on something other than macOS, since patch-app and restore-app are macOS only. Before you rely on it, run codex-shim status after codex-shim start and confirm the provider entry landed in ~/.codex/config.toml, and treat the token reduction numbers in the README as the maintainer anecdote it says they are.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. sybil-solutions/codex-shim on GitHub