The Problem

Codex CLI, App, and SDK users who want to run tasks with non-OpenAI models face a proxy gap: there is no universal translator between Codex's Responses API and arbitrary LLM providers. Each provider requires custom integration code, and maintaining separate adapters for Claude, Gemini, Grok, DeepSeek, Ollama, and others creates operational overhead. Teams either lock to OpenAI or build fragile homegrown proxies that break when Codex updates its API shape.

What This Does

opencodex is a lightweight local proxy that translates Codex's Responses API into whatever provider speaks the target LLM. The core routing lives in src/cli.ts and src/server/index.ts, which accept Codex's /v1/responses calls and forward them to the configured upstream. Provider selection and auth are managed from src/oauth/index.ts and src/codex/catalog.ts — the latter is a hub module with 211 dependents and instability 0.36, meaning changes ripple widely across the codebase. The provider registry at src/providers/registry.ts is oversized at 807 lines, and src/config.ts (87 importers, 4 imports, instability 0.04) is the most-connected config point. A circular import exists between src/codex/catalog.ts and src/codex/model-cache.ts, which must be broken for stable evolution. The dashboard UI at gui/src/App.tsx and i18n at gui/src/i18n/index.ts (27 importers, 2 imports, instability 0.07) handle the user-facing configuration and account pooling.

How It Is Wired

Execution starts at the CLI entry src/cli.ts, which parses ocx start and boots the Express-based proxy server at src/server/index.ts. Incoming Codex requests hit src/server/responses.ts (10 importers, 34 imports, instability 0.77 — high branching density at 233 branch points over 807 lines), where the request is normalized, auth is checked via src/oauth/index.ts (22 importers, 18 imports, instability 0.45), and the target provider is resolved from the catalog. The catalog then delegates to the registered provider implementation. Environment variables and keys are read from src/lib/service-secrets.ts, which the code-health audit flags for secret-shaped paths. The proxy supports both streaming and non-streaming Responses API paths, and routes tool calls, reasoning tokens, and images in both directions. The account-pooling logic ensures existing Codex threads stay pinned to their originating account while new sessions route to the lowest-usage healthy account.

How To Use It

Setup: npm install -g @bitkyc08/opencodex (Node 18+; Bun bundled automatically). Configuration: Run ocx init to write config and inject into Codex. The config file (generated during init) holds provider keys and account pool settings. Running it: ocx start launches the proxy server (entry point src/server/index.ts). Default URL is localhost:10100. Auth management: Use the dashboard at localhost:10100 to add ChatGPT/Codex accounts, refresh 5h/weekly/30d quotas, and let new sessions auto-route to the lowest-usage healthy account.

Real-World Use

A development team wants to run Codex-powered code reviews using a Claude model instead of OpenAI. They install opencodex, run ocx init to configure the Claude API key, and start the proxy with ocx start. Codex CLI commands now route through the proxy to Anthropic's endpoint. When a new review session starts, opencodex's account-pool logic directs it to the Claude account with the most remaining quota; existing threads remain pinned to their original account so SSH, tmux, or mobile sessions don't jump mid-conversation. If a 429 rate limit occurs, the proxy enters a cooldown and failover to the next healthy account.

Code Health & Issues

  • [HIGH] Stop discarding the exit code of steps whose failure matters — .github/workflows/release.yml lines 255 discard failure, so the job reports green while the artifact was never produced.
  • [MEDIUM] Enable Dependabot or Renovate — 3 manifest(s), no update bot configured; without a bot a published advisory sits unpatched until someone audits by hand.
  • [MEDIUM] Gate pull requests on a dependency vulnerability scan — no dependency scan in CI; this is the one gate that would catch a known-vulnerable package before it reaches a build.
  • [MEDIUM] Set persist-credentials: false on checkout — .github/workflows/ci.yml checkout keeps the token, so a malicious postinstall script could read a pushable credential without one ever being passed to it.
  • [HIGH/soundness] Import cycle member — src/codex/catalog.ts and src/codex/model-cache.ts participate in a circular import dependency.
  • [HIGH/cognitive_load] Oversized file — src/config.ts, src/codex/catalog.ts, src/providers/registry.ts at 807 code lines; hard to hold in one head and changes ripple widely.
  • [MEDIUM/cognitive_load] High branching density — src/config.ts, src/codex/catalog.ts, src/responses/parser.ts at 233 branch points over 807 lines.
  • [MEDIUM/cognitive_load] Deep nesting — src/bridge.ts max indentation depth 6; control flow is hard to follow.
  • [Low/Risk] Dependencies declared without a lockfile — docs-site/package.json; non-reproducible builds.
  • [Low/Security] Secret-shaped paths present — src/lib/service-secrets.ts; confirmed by code-health audit.

The Bottom Line

opencodex delivers on its promise: a working proxy that lets Codex CLI, App, and SDK talk to virtually any LLM provider without waiting for official support. The architecture is functional and the account-pooling feature is genuinely useful for teams sharing Codex accounts. However, the codebase carries significant technical debt — the oversized registry and config files, the import cycle, and the CI hygiene gaps (no lockfile, no dependency scanning, credential mismanagement) are real risks for anyone planning to operate this in production. It's suitable for teams that need provider flexibility today and are willing to invest in refactoring the hub modules and fixing the CI pipeline. Teams requiring out-of-the-box stability and security hardening should look elsewhere or budget for the mentioned remediation work.