opencodex

Universal provider proxy for OpenAI Codex & Claude Code. Use Claude, Gemini, Grok, DeepSeek, or any LLM with Codex CLI/App/SDK — streaming, tool calls, and reasoning tokens all work.

Comment

Inspiration

OpenAI Codex is an incredibly powerful coding agent, but it only works with OpenAI's own models. We wanted to unlock the full potential of Codex by letting developers use any LLM — Claude, Gemini, Grok, DeepSeek, Qwen, Ollama, and 50+ more providers — without waiting for official support. The same goes for Claude Code: why be locked into one provider when you can route to whatever model fits the task?

The moment GPT-5.6 shipped, we had a working proxy in hours. That's the point — new models show up fast, and your tooling should keep up.

What it does

opencodex is a lightweight local proxy that sits between Codex (CLI, App, or SDK) and any LLM provider. It translates Codex's Responses API into whatever protocol your provider speaks — Anthropic Messages, Google Gemini, Azure, or any OpenAI-compatible Chat Completions endpoint. Streaming, tool calls, reasoning tokens, and images all work bidirectionally.

In practice, you npm install, run ocx init, and Codex just works with whichever model you pick from the dashboard. No config files to hand-edit, no environment variables to juggle.

Key features:

  • Universal model routing — Use provider/model syntax (e.g. anthropic/claude-opus-4-8, google/gemini-3-pro) to target any of 50+ configured providers
  • Claude Code support — The same daemon serves the Anthropic Messages API, so ocx claude launches Claude Code fully wired with model discovery
  • ChatGPT account pooling — Add multiple ChatGPT/Codex accounts, auto-route new sessions to the lowest-usage healthy account, while existing threads stay pinned
  • OAuth login — One-click login for xAI, Anthropic, and Kimi; tokens auto-refresh
  • Web dashboard — See providers, OAuth status, model selection, and live request logs at localhost:10100
  • Background service — Install as launchd/systemd/Task Scheduler and forget about it
  • Sidecar superpowers — Non-OpenAI models get web search and image understanding via a gpt-5.4-mini sidecar
  • Multi-agent delegation — Feature up to 5 models in Codex's subagent picker for task-appropriate routing

How we built it

opencodex is built with TypeScript running on the Bun runtime (bundled automatically via npm — no separate Bun install needed). The proxy architecture centers on five protocol adapters:

  1. openai-responses — passthrough for native OpenAI
  2. anthropic — Anthropic Messages API translation
  3. google — Google Gemini API
  4. azure-openai — Azure OpenAI endpoints
  5. openai-chat — universal adapter for any OpenAI-compatible Chat Completions endpoint

The web dashboard is a React SPA served from the proxy itself. The CLI (ocx) handles setup, service management, and Codex injection. On install, opencodex points Codex's built-in openai provider at itself via a single openai_base_url line — fully reversible with ocx stop.

We used GPT-5.6 extensively during development: the Codex App handled most of the protocol adapter work, large refactors, and cross-platform service integration. The irony of using Codex to build a tool that makes Codex work with non-OpenAI models was not lost on us.

Challenges we ran into

  • Protocol translation fidelity — Mapping Codex's Responses API to Anthropic Messages, Google Gemini, and Chat Completions while preserving streaming, tool calls, and reasoning tokens required careful bidirectional translation. Each provider has its own quirks: Anthropic's thinking blocks, Google's functionCall format, and the dozen ways different providers handle streaming deltas.
  • Account pool affinity — Keeping existing Codex threads pinned to their original ChatGPT account while auto-routing new sessions demanded a reliable affinity system. A thread that jumps accounts mid-conversation loses its history.
  • Cross-platform services — Supporting launchd (macOS), systemd (Linux), and Task Scheduler/WinSW (Windows) natively without WSL. Each platform has different privilege models and lifecycle semantics.
  • History safety — Ensuring that Codex's chat history is never corrupted when the proxy injects itself, and that ocx stop restores everything cleanly — even after a crash.

Accomplishments that we're proud of

  • 2,100+ GitHub stars and growing community adoption within weeks of launch
  • 50+ providers supported out of the box with 5 protocol adapters
  • Works on all three major platforms (macOS, Linux, Windows) natively — no WSL, no Docker
  • Zero-residue uninstall — ocx stop restores Codex to its exact original state
  • Claude Code integration with full gateway model discovery
  • The project is fully self-hosting: we develop opencodex using Codex routed through opencodex

What we learned

Every provider API looks similar on the surface, but the devil is in the streaming. Anthropic sends content_block_delta events, Google wraps tool calls in functionCall, and some OpenAI-compatible providers silently drop fields they don't understand. Building a universal translator meant writing adapter code that handles these edge cases without leaking abstractions to Codex.

We also learned that safe injection is harder than it sounds. Modifying another tool's config must be reversible, history-safe, and crash-resilient. One bad write to Codex's config mid-session could corrupt an entire conversation tree.

What's next for opencodex

  • Expanding the multi-agent delegation surface so you can mix Claude for architecture review, GPT-5.6 for implementation, and a local model for quick iterations — all in the same Codex session
  • Deeper Claude Code integration with workspace-aware routing
  • Community-contributed provider adapters (we already have PRs from the community)
  • Enhanced quota analytics and cost tracking across providers

Built With

Share this project:

Updates