opencodex

npm install -g @bitkyc08/opencodex
ocx start        # proxy + dashboard on localhost:10100

opencodex is a lightweight local proxy that translates Codex's Responses API into whatever your provider speaks — streaming, tool calls, reasoning tokens, images, in both directions. Use Claude, Gemini, Grok, GLM, DeepSeek, Kimi, Qwen, Ollama, or any other LLM with Codex, Claude Code, Claude Desktop, and Grok Build. It can also manage a ChatGPT account pool for Codex auth: add accounts, refresh their quotas in the dashboard, and let new sessions auto-route to the lowest-usage healthy account while existing threads stay pinned to the account that started them.

Quick start

For humans

npm install -g @bitkyc08/opencodex   # Node 18+; the Bun runtime is bundled automatically
ocx start                            # or `ocx service` to run it in the background

macOS / Linux:

curl -fsSL https://bun.sh/install | bash && ~/.bun/bin/bun upgrade --canary
git clone https://github.com/lidge-jun/opencodex.git
cd opencodex && ~/.bun/bin/bun install
~/.bun/bin/bun run src/cli/index.ts start

Windows (PowerShell):

irm bun.sh/install.ps1 | iex; bun upgrade --canary
git clone https://github.com/lidge-jun/opencodex.git
cd opencodex; bun install
bun run src/cli/index.ts start

Source install runs the latest dev branch with Bun canary. Memory ownership patches, runtime GC improvements, and unreleased fixes are available here before they reach the npm package.

Open http://localhost:10100 and configure everything in the web dashboard — add providers (40+ built-ins, or any OpenAI-compatible endpoint), pick models, manage accounts. ocx gui re-opens the dashboard at any time. It can also manage a ChatGPT account pool for Codex auth. Add multiple ChatGPT / Codex accounts, refresh their 5h / weekly / 30d quota in the dashboard. Under quota routing, new sessions can use the lowest-usage healthy account; round-robin and fill-first use their own policies. Existing Codex threads normally retain affinity to the account that started them, so long SSH, tmux, or mobile-connected sessions do not jump accounts mid-conversation — but quota re-evaluation, failover, account exclusion, affinity expiry, or 401/403 and 429 recovery can rebind them. Give the accounts a selection order when one of them — usually your Codex Desktop login — should only be reached for once the others are drained.

For agents

npm install -g @bitkyc08/opencodex
ocx start     # or `ocx service`
ocx init      # interactive setup: writes ~/.opencodex/config.json and wires Codex

ocx init never starts the proxy; start it first (or after — either order works, but headless commands like ocx provider add and ocx combo set talk to the live proxy and exit nonzero when it is unreachable). ocx status / ocx doctor / ocx health report the running state.

Agents installing or running opencodex: read AGENTS_INSTALL.md. An interactive ocx start may ask once whether to star this repository — that is the user's decision, never an agent's. The CLI suppresses the prompt for agent-driven runs and the API refuses them with 403 agent_consent_required.

Supported platforms

Requires Node 18+. The Bun runtime is bundled on npm install — no separate Bun install needed, no WSL needed on Windows. If npm blocked the bundled runtime's install scripts, see the installation docs.

Highlights

• Use any LLM with Codex, Claude Code, Claude Desktop, and Grok Build — 40+ providers out of the box, each keeping its own native UI.
• Pool ChatGPT accounts safely — thread affinity, quota-aware auto-switching, cooldown and fail-closed auth handling.
• Combos — one virtual model id with failover or weighted round-robin across providers. See the combo guide.
• Sub-agents on any model — feature routed models in Codex's sub-agent picker, with v1/v2 surface control and fallback chains. See the sub-agent guide.
• Log in once, skip the API key — OAuth for xAI, Anthropic, and Kimi; or forward codex login, paste a key, or use ${ENV_VAR} references.
• Web search & vision sidecars — non-OpenAI models get real web search and image understanding through a sidecar over your ChatGPT login.
• See what's happening — the dashboard shows providers, OAuth status, model selection, and a live request log with cache token counts.
• Clean exit, zero residue — ocx stop restores Codex to its original configuration.
• Bounded memory ownership — every long-lived cache, ring buffer, and protocol-translation store has a finite cap, byte budget, or active reconciliation. No unbounded Map or Set survives a config reload.

OpenCodex tracks 36 categories of process-retained state. Each has a documented bound:

• 12 retained stores (request log, debug rings, image cache, model cache, vision descriptions, cursor blobs, responses continuation, etc.) are byte-accounted and evicted by the app-owned memory budget (default 256 MiB).
• 4 observed buffers (translator accumulators, image/OAuth/Grok tails) are monitored for in-flight byte pressure without eviction.
• 24 state-store registrations handle expiry sweeps (60 s interval) and config-generation reconciliation so stale provider/account keys are removed.
• Path and fingerprint memos (workspace metadata, hardened identities, installation salts, mode-hint capabilities) use insertion-order LRU caps (8–128 entries).
• Model-cache generation tombstones are deleted after reconciliation; a global generation increment prevents stale in-flight discoveries from repopulating removed providers.
• Lab event-id deduplication runs under a ledger lock from disk, with no process-level RAM index.

Run GET /api/system/memory (with the admin token) to inspect live retained bytes, eviction counters, and watchdog samples.

Model routing

Target any configured provider and model with the provider/model syntax:

codex -m "anthropic/claude-opus-5" "Explain this stack trace"
codex -m "google/gemini-3-pro" "Write unit tests for auth.ts"
codex -m "ollama/llama3" "Refactor this function"

Omit the provider/ prefix to use the default provider or auto-match by model name pattern. Provider model ids containing / are exposed with inner slashes aliased to -; the raw full-slash form keeps working too. Details: model routing docs.

Providers & adapters

OpenAI (ChatGPT login or API key), Anthropic, Google Gemini, xAI, Kimi, Azure OpenAI, Ollama (local + Cloud), Cursor (experimental), and every OpenAI-compatible endpoint — plus DeepSeek, Groq, OpenRouter, Together, Fireworks, Cerebra