Enables Codex Desktop users to integrate custom Bring-Your-Own-Key (BYOK) models and optionally a ChatGPT GPT-5.5 passthrough, bypassing the application's default model whitelisting. This project serves as a local Python server shim, acting as an OpenAI-compatible API endpoint, allowing for expanded model selection within Codex Desktop without recompiling the application.

How It Works

The project provides a local Python server that emulates the OpenAI Responses API. Codex Desktop is configured to point to this local shim. The shim reads model configurations from a specified JSON file (defaulting to ~/.factory/settings.json), generates a catalog of available models, and routes incoming requests to the appropriate upstream API provider (e.g., OpenAI, Anthropic, generic chat completion APIs, or ChatGPT). It handles the translation between Codex Desktop's request format and the upstream API's requirements, including streaming responses.

Quick Start & Requirements

• Installation: Clone the repository, install runtime dependencies (aiohttp, pytest) via pip install --user, and symlink the provided binaries (codex-shim, codex-app, codex-model) to a directory in your PATH (e.g., ~/.local/bin/).
• Prerequisites: Python 3.11+.
• Setup: Run codex-shim generate to create a model catalog from ~/.factory/settings.json, then codex-shim start to launch the local server daemon on 127.0.0.1:8765. Launch Codex Desktop with the shim wired in using codex-shim app ..
• Documentation: Official quick-start commands are provided in the README.

Highlighted Details

• Supports BYOK models from providers like OpenAI, Anthropic, Z.ai, DeepSeek, Gemini, and OpenRouter.
• Includes an optional passthrough for ChatGPT subscription's GPT-5.5.
• Acts as a local OpenAI Responses API shim, translating requests and responses.
• Forwards generic MCP (Model Configuration Protocol) tools to shim-routed models.

Maintenance & Community

The project is tested on Codex Desktop 0.133.0-alpha.1 for macOS arm64. No specific details on contributors, sponsorships, or community channels (like Discord/Slack) are provided in the README.

Licensing & Compatibility

The project is licensed under the MIT License. Codex Desktop is a trademark of OpenAI, and this project is unaffiliated. The MIT license generally permits commercial use and integration with closed-source applications.

Limitations & Caveats

On macOS, enabling custom models in the Codex Desktop picker requires a complex, multi-step ASAR patching process involving command-line tools and code modification, which carries a risk of application instability or crashes if not performed correctly. Linux and Windows users may bypass this specific patch. The project is tested against an alpha version of Codex Desktop, suggesting potential compatibility issues with future stable releases.