Codex Router

# Codex Router

## Install everything (recommended)

This is the default setup: **guided provider setup + Electron Control Center +
tray/menu-bar app + macOS desktop widget**.

### macOS or Linux

Copy and paste this into Terminal:

```sh
curl -fsSL https://raw.githubusercontent.com/duolahypercho/codex-router/main/install.sh \
  | sh -s -- --target codex --guided --with-tray
```

### Windows

Copy and paste this into PowerShell:

```powershell
$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
```

That is the complete installation. It asks which providers you want and keeps
credential entry in private local prompts.

When it finishes:

1. Fully quit and reopen Codex.
2. Start a new task and choose a routed model.
3. Open **Codex Router** to use the Control Center.

On macOS, open **Codex Router** from Spotlight or `~/Applications`; its icon
stays in the menu bar when the Control Center is closed. The desktop widget is
already included: choose **Settings → Dynamic Island → Desktop** from the
menu-bar app to show it. It is a movable Codex Router panel rather than an item
in macOS's **Edit Widgets** gallery.

macOS does not have a public `.dmg` yet; the command above builds and installs
the app locally. That build requires the full Xcode app, not only the standalone
Command Line Tools, because it contains SwiftUI macro and WidgetKit targets. The
installer honors `DEVELOPER_DIR` or the Xcode selected under **Xcode → Settings
→ Locations → Command Line Tools**. If that selection still points at the
standalone tools, it uses `/Applications/Xcode.app` or
`/Applications/Xcode-beta.app` for this build only without changing the global
selection. For an Xcode app in another location, retry the companion with:

```sh
env DEVELOPER_DIR="/path/to/Xcode.app/Contents/Developer" \
  ~/.local/share/codex-router/bin/model-router-tray
```

## What Codex Router does

Use Anthropic, Kimi, DeepSeek, xAI, GitHub Copilot, and other external models
inside the Codex App and CLI. One local installation can also serve
[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) and
[Gemini CLI](https://github.com/google-gemini/gemini-cli), plus Cursor Agent
and Cursor App, Claude Code, and [OpenClaw](https://github.com/openclaw/openclaw).
Your provider
credentials stay on your computer.

### Subscription agent bridges (experimental)

The Harness page also detects three optional, client-owned agent sessions:
Claude Code, Cursor Agent, and Gemini CLI. These are deliberately separate from
the `codex_router/...` model catalog:

- Claude runs through the installed official `claude` process and its existing
  Claude.ai login. A successful `claude auth status` proves login only; the
  account must separately be entitled to use non-interactive/SDK turns. The
  bridge reports Anthropic's refusal verbatim when it is not.
- Cursor Agent runs through its official ACP stdio server (`agent acp`).
- Gemini CLI runs through its official ACP stdio server (`gemini --acp`).

The router never reads or copies those clients' OAuth tokens. It stores only
bounded metadata for sessions created through the bridge: client, session ID,
workspace path, and timestamps. Prompts and transcripts stay out of the bridge
index. File-system and terminal capabilities are not advertised yet, and
permission requests are rejected by default until the Control Center has a
foreground approval surface.

This is not an OpenAI-compatible subscription proxy. In particular, it does
not implement CLIProxyAPI's token-to-model-endpoint behavior and does not add
fake Claude, Cursor, or Gemini subscription models to another client's picker.

Inspect the optional bridges without spending a model request:

```sh
./bin/model-router codex agents status
./bin/model-router codex agents probe anthropic
./bin/model-router codex agents probe cursor
./bin/model-router codex agents probe gemini
```

Run a prompt only when you intend to spend the owning client's quota. Prompt
text is read from stdin so it is absent from the process list:

```sh
printf '%s' 'Explain this repository.' |
  ./bin/model-router codex agents prompt anthropic --cwd "$PWD"
```

Claude prompts also accept `--model` and `--effort`, including when resuming
with `--session`. See the [adaptive worker routing pilot](docs/experiments/adaptive-worker-routing.md)
for the supported controls and an offline comparison of routing policies.

The ACP integrations follow the official [Cursor ACP](https://prod.cursor.com/docs/cli/acp)
and [Gemini CLI ACP](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/acp-mode.md)
contracts. Direct reuse of Gemini CLI OAuth tokens in third-party software is
not implemented; Google's published [Gemini CLI terms](https://github.com/google-gemini/gemini-cli/blob/main/

... (truncated)