duolahypercho/codex-router

Codex Router – a multi‑provider LLM gateway for the Codex app

What it is

• A community‑maintained utility that lets the Codex desktop/CLI application talk to many external large‑language‑model (LLM) providers (Anthropic, Kimi, DeepSeek, xAI/Grok, Gemini, GitHub Copilot, Ollama Cloud, etc.) without exposing your API keys to the Codex app itself.
• It installs a background service, an optional Electron‑based Control Center (tray/menu‑bar app with a macOS Dynamic Island widget), and command‑line helpers that manage provider credentials, model catalogs, and optional search side‑cars.

How you get it

• Recommended one‑click installer (macOS/Linux/Windows) – runs a shell/PowerShell script that builds the Electron UI locally, prompts you to pick providers, and stores credentials in a private, hidden prompt.
• Homebrew formula – installs only the CLI (codex-router command) and its Node/Python dependencies; you must run codex-router setup --guided afterwards to finish provider selection.
• Guided installer – same script as the recommended installer but without the tray/widget (--guided only).

Core capabilities

Feature	Description
Provider routing	After setup you can start a Codex task and select a routed model from a picker. The router forwards the request to the chosen external API, adding any required OAuth or API‑key headers.
Credential safety	API keys and OAuth tokens are never typed into the chat UI; they are entered once through a hidden terminal prompt and stored in a per‑user, owner‑only state directory.
Model catalog	The router builds a dynamic list of models (see the extensive table in the README) that appear only when the corresponding credential is present. Native OpenAI models appear only after codex login succeeds.
Search side‑car	For models that lack built‑in web‑search, you can bind a Perplexity Search provider that implements the raw POST /search API. The side‑car is model‑specific and its credential is also kept private.
Cross‑platform UI	On macOS the Control Center lives in the menu bar and can show a movable “Dynamic Island” desktop widget. Linux gets the CLI only; Windows gets PowerShell wrappers (codex-router.ps1).
Extensible provider system	You can add generic providers (e.g., Perplexity) via model-router codex providers generic add … and then bind them to a specific model.
Safety checks	The installer can run in a credential‑free mode (--no-provider --no-discovery) that installs the service but never reads any keys, allowing you to verify the install/uninstall lifecycle first.

Supported providers & authentication styles

• OAuth‑based (Kimi, Grok, Antigravity) – reuses the official CLI’s OAuth session.
• API‑key‑based (DeepSeek, MiniMax, Qwen, ClinePass, Xiaomi MiMo, etc.) – keys are stored securely and never passed on the command line.
• Ollama Cloud – uses an Ollama Cloud API key.
• GitHub Copilot – requires a fine‑grained GitHub PAT with Copilot Requests permission; the router does not read the official Copilot CLI store.
• Antigravity (Google Gemini internal) – optional, requires a private client secret supplied by the operator; not available in public builds.

Typical workflow

1. Run the installer (curl … | sh -s -- --target codex --guided --with-tray).
2. Choose which providers you want; the installer will prompt you for any needed OAuth login or API key.
3. Quit and reopen the Codex app.
4. Create a new task, pick a routed model from the dropdown.
5. (Optional) Open Codex Router from the menu bar to view status, change providers, or manage search side‑cars.

Limitations / notes

• The project is not affiliated with any of the listed providers (OpenAI, Anthropic, Google, etc.).
• macOS does not yet ship a pre‑built .dmg; the installer compiles the Electron app locally.
• The Homebrew formula does not include the Electron UI; it only provides the codex-router CLI.
• Some providers (e.g., Antigravity) need a private client secret that is not distributed publicly.
• Search side‑cars are per‑model; you cannot enable a global fallback search.
• The router does not alter the underlying Codex client’s native GPT models – those continue to be accessed directly via the existing OpenAI login.

Where to learn more

• Full installation guide: docs/INSTALL.md
• Homebrew contribution guide: docs/HOMEBREW_CORE.md
• Provider‑specific notes are embedded in the README’s large model/credential table.

---

All details above are taken directly from the repository’s README; no additional features have been inferred.