Every install command in codex-shim clones a different repository
Local Responses-API shim that exposes Factory BYOK models (and optional ChatGPT GPT-5.5 passthrough) to Codex Desktop.
At a glance
- What is it?
- codex-shim is a local Python and aiohttp server that puts an OpenAI Responses-compatible endpoint on loopback so Codex Desktop can route to models you already pay for. Its routing layer is careful about tool calls and streaming, its subscription passthrough reads existing local auth files, and its own documentation points every install command at a different GitHub account than the tree it ships in.
- Who is it for?
- Read the terms of your own ChatGPT and Cursor subscriptions before you point a local process at their credentials, because the passthrough features work by reading auth files that already exist on your machine rather than by using an API key meant for that purpose.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 34 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- sybil-solutions/codex-shim1,071 ★ · +7
| Repository | 2026-09-21 | 2026-11-15 |
|---|---|---|
| sybil-solutions/codex-shim | 1.1k | 1.1k |
7 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The documented clone command fetches another repository
Every address in the installation instructions points somewhere other than the repository holding them. The recommended clone command on macOS, Linux, WSL and Git Bash is:
git clone https://github.com/0xSero/codex-shim ~/codex-shim
cd ~/codex-shim
python3 -m pip install --user -e .The native Windows variant clones the same account, and the manifest agrees: its Homepage, Repository and Issues URLs all resolve to github.com/0xSero/codex-shim, with the author recorded as 0xSero. This tree, meanwhile, is published under a different owner and name. So the two are consistent with each other and inconsistent with the page you read them on, which means a reader who follows the instructions literally ends up installing a checkout they did not choose, with no note in the text explaining the difference.
Subscription passthrough works by reading auth files you already have
Two features avoid API keys by borrowing credentials already on the machine. For ChatGPT, if the Codex auth file at ~/.codex/auth.json contains a valid Codex access token, the shim routes Codex's native /v1/responses traffic to the ChatGPT Codex backend under the gpt-5.5 slug that current Codex builds use. For Cursor, an active cursor-agent login is enough to expose a composer-2-5 entry that routes through a Cursor subscription with no Dashboard API key required. Both are described as passthrough rather than as a new integration, and the routing happens in a local process on loopback. That framing matters for anyone deciding whether this is acceptable use, since what is being reused is a subscription credential in a path its issuer did not build.
The routing layer translates tool calls instead of flattening them
Codex speaks the Responses shape, so the shim accepts that on loopback and forwards each request to whichever upstream matches: OpenAI chat completions, Anthropic Messages, a generic OpenAI-shaped chat endpoint, or the ChatGPT passthrough. The return trip is where the work is, because streaming responses have to come back in the shape Codex expects. The stated design keeps the native agent loop intact rather than degrading it, translating function calls, tool outputs, reasoning blocks, image-capable models, shell-command metadata and streaming server-sent events. The practical test for any upstream is whether tool metadata survives the round trip, and the maintainers point at exactly that list rather than at text quality. Binding is to 127.0.0.1, so nothing here is exposed to the network by default.
The picker entry needs a patched, signed app bundle on macOS
Codex Desktop only shows models its server-side config allows, which is the whole reason the shim exists: without intervention, your own models never appear in the picker. The fix is optional and macOS-only. The patch-app and restore-app commands target /Applications/Codex.app and the Electron ASAR signing that goes with it, and they need npx and codesign present. The Windows setup table is explicit about the boundary: native PowerShell, WSL and Git Bash are all supported for the shim itself, but the bin/ wrappers for codex-app and codex-model are listed as not native, because they are shell scripts, and patch-app and restore-app are marked macOS only. For Windows convenience there is a Launch Codex-Shim.bat and a launch.ps1 at the repository root.
Two install routes, and symlinks that break if you move the checkout
There are two documented ways in, and the difference is whether the package is installed or merely reachable. The recommended route installs the codex-shim entry point from pyproject.toml with pip, which pulls in aiohttp and gives you a portable console command. The alternative skips installation entirely: install aiohttp yourself, create ~/.local/bin, and symlink the three scripts in bin/, codex-shim, codex-app and codex-model. That second route has a documented consequence, since moving the checkout leaves the symlinks pointing at nothing, and the text says to recreate them. It also offers a way out, noting that codex-shim app launches codex app through the installed Python entry point and does not need them at all. For PATH problems there is an export line for POSIX shells, the Python user Scripts directory for PowerShell, and a module form that bypasses PATH completely.
The performance claim is labelled anecdotal by its own author
There is exactly one performance claim in the documentation, and it comes with a disclaimer attached. In the maintainer's internal Codex tasks, ChatGPT passthrough combined with a prompt-catching proxy in front of the shim produced multi-x reductions in billed input tokens and noticeably faster wall time against the baseline route. The next sentence says no reproducible benchmark script ships with the repository, and that the benchmark section explains how to measure your own setup against an explicit oracle before quoting numbers. That is an unusually careful framing for a project README, and it also means the token savings are a property of that proxy arrangement rather than of the shim alone. The optional Auto Router is described the same way: a cheap classifier model routes each task to the cheapest configured model able to handle it.
Alpha packaging, one dependency, and two self-descriptions
The manifest is small and honest about its own state. The version is 0.1.0, the development status classifier says Alpha, the single runtime dependency is aiohttp 3.9 or newer, and the dev extras are pytest 8 or newer with pytest-asyncio, with pytest configured to collect from tests/ in asyncio auto mode. No GitHub releases are published at all, so installation is a clone plus a local editable install rather than a package download, and the last push to this repository is dated 25 August 2026. Two small mismatches sit alongside that. The classifiers list only Python 3.11 and 3.12 while the requirement is 3.11 or newer with no upper bound, and the repository description talks about Factory BYOK models where the manifest calls itself a local all-model BYOK shim for Codex Desktop and CLI.
Editorial conclusion
Read the terms of your own ChatGPT and Cursor subscriptions before you point a local process at their credentials, because the passthrough features work by reading auth files that already exist on your machine rather than by using an API key meant for that purpose. Then check what you are actually installing, since the documented clone command fetches a different repository than the one you are reading, and expect alpha software: no releases, a 0.1.0 manifest, and a single runtime dependency. Anyone who needs measured cost numbers rather than a maintainer's anecdote should build their own oracle first.
Frequently asked questions
What does codex-shim need before it will run?
Python 3.11 or newer, an installed and authenticated Codex CLI or Desktop, and one of three inputs: a models.json under ~/.codex-shim, a compatible JSON file passed with the settings option, or a Codex auth file at ~/.codex/auth.json containing an access token for passthrough-only use.
Does codex-shim require rebuilding or patching Codex?
No rebuild is needed, since it is a local Python and aiohttp server exposing a Responses-compatible endpoint on loopback that Codex points at. The one exception is the optional desktop picker patch, which targets /Applications/Codex.app and its ASAR signing and is macOS only.
Which upstreams can codex-shim route requests to?
OpenAI chat completions, Anthropic Messages, a generic OpenAI-shaped chat endpoint, and the ChatGPT Codex passthrough. The models file is described as covering OpenAI, Anthropic, Z.ai, DeepSeek, Gemini, OpenRouter and local proxy models.
What performance evidence does codex-shim provide?
Only an anecdotal note from the maintainer's own internal Codex tasks, where ChatGPT passthrough plus a prompt-catching proxy gave multi-x reductions in billed input tokens and faster wall time against the baseline route. No reproducible benchmark script ships with the repository.
Is codex-shim published as a release anywhere?
No GitHub releases exist for it. The manifest version is 0.1.0 with a development status of Alpha, aiohttp is the only runtime dependency, and the documented installation is a clone followed by a pip install from that checkout.
Can other local software see what I send through codex-shim?
The shim itself binds to 127.0.0.1, but the documentation proposes putting a local proxy in front of it to dedupe boilerplate, inject stable instructions, repair pseudo-tool text or route prompts by policy. A process in that position sees and can rewrite every prompt on its way to an upstream.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/sybil-solutions-codex-shim)Star history chart for your README
[](https://hysenlabs.com/projects/sybil-solutions-codex-shim)Was this useful?