duolahypercho/codex-router

What is Codex Router?

Codex Router is a client‑side routing layer that lets the Codex desktop/CLI application talk to many different large‑language‑model (LLM) providers – Anthropic, Kimi, DeepSeek, xAI (Grok), GitHub Copilot, Claude, Gemini, and dozens of others – without you having to switch apps or manually manage API keys.

It installs a small background service, an Electron‑based Control Center (with a tray/menu‑bar app and a macOS Dynamic Island widget), and a command‑line tool (model-router). The service stores your provider credentials locally (via hidden prompts) and presents the combined model catalog inside Codex, so you can pick a “routed model” when you start a task.

Key features (as described in the README)

• Multi‑provider support – works with OAuth‑based sessions (e.g., Kimi Code, Grok, Claude) and plain API‑key providers (DeepSeek, StepFun, Qwen, etc.).
• Subscription‑agent bridges (experimental) – optional, read‑only bridges to existing Claude, Cursor, and Gemini CLI agents that let Codex route prompts through those tools without exposing their OAuth tokens.
• Secure credential handling – credentials never leave the machine; the router only stores minimal metadata (session IDs, timestamps) and never logs prompt text.
• Cross‑platform installers – a guided installer script for macOS/Linux, a PowerShell installer for Windows, Homebrew formula, and future npm package plans.
• Desktop integration – a menu‑bar/tray app and a movable macOS widget (Dynamic Island) that act as a “Control Center” for enabling/disabling providers, viewing usage, and configuring routing policies.
• Extensive model catalog – the README lists dozens of model IDs, each paired with the required authentication method (OAuth session, API key, or Ollama Cloud). The router only shows models for which a valid credential is present.
• No fake subscription proxy – it does not emulate OpenAI’s token‑to‑endpoint behavior; it simply forwards requests to the selected provider.

Who is it for?

• Codex users who want to experiment with many LLM back‑ends without leaving the Codex UI.
• Developers who need a single place to manage API keys/OAuth sessions for a variety of LLM services.
• Teams that want to keep credentials local and avoid exposing them to third‑party proxies.

How to install (quick start)

# macOS / Linux (guided, with tray widget)
curl -fsSL https://raw.githubusercontent.com/duolahypercho/codex-router/main/install.sh \
  | sh -s -- --target codex --guided --with-tray

# Windows
$installer = Join-Path $env:TEMP "codex-router-install.ps1"
Invoke-WebRequest https://raw.githubusercontent.com/duolahypercho/codex-router/main/install.ps1 -OutFile $installer
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $installer -Target codex -Guided -WithTray

The script walks you through selecting providers, logging in (e.g., kimi login), and installing the background service. After it finishes, quit and reopen the Codex app, start a new task, and you’ll see the routed models in the picker.

Typical workflow

1. Run the installer – choose which providers you want.
2. Authenticate – the installer opens hidden terminal prompts for API keys or OAuth logins.
3. Open Codex Router Control Center – from Spotlight (macOS) or the tray icon.
4. Select a routed model when creating a Codex task.
5. (Optional) Use bridges – e.g., ./bin/model-router codex agents probe anthropic to check a Claude or Gemini bridge.

Example command‑line usage

# List available agents
./bin/model-router codex agents status

# Send a prompt to Anthropic via the bridge (reads from stdin)
printf '%s' 'Explain this repository.' |
  ./bin/model-router codex agents prompt anthropic --cwd "$PWD"

Project status

• Community‑maintained, not affiliated with any of the listed providers.
• Experimental bridge support for Claude, Cursor, and Gemini.
• macOS widget built with SwiftUI/WidgetKit; Windows and Linux rely on the Electron UI.
• Homebrew tap available for CLI‑only installs; npm package planned.

---

All details above are taken directly from the repository’s README.