codex-multi-auth

codex-multi-auth is a multi-account OAuth manager for the official @openai/codex CLI. It keeps a named pool of ChatGPT sign-ins on your machine, lets you switch the active account, and — when you run Codex through its optional wrapper — rotates accounts across live requests through a loopback-only proxy. It never installs or shadows a codex binary; the official OpenAI install keeps owning that command.

Use it when one Codex account is not enough: you hit rate limits or quota windows, you split work across organizations and workspaces, you want per-project account pools, or you run unattended agents that need JSON diagnostics and safe repair commands instead of one opaque auth file.

Using OpenCode rather than the Codex CLI? The sibling project oc-codex-multi-auth is the plugin that manages the same kind of account pool there.

What it does

• Account pool — OAuth login for multiple ChatGPT accounts, stored locally under ~/.codex/multi-auth (files 0600, directories 0700), with per-project pools under projects//.
• Switching and selection — pin an account, pick the forecast-best one, follow saved account order within customized priority tiers with sequential scheduling, or let health- and quota-aware hybrid selection rotate for you.
• Runtime rotation — a default-on, loopback-only proxy that forwards Responses API, model-discovery, image, thread-goal, and Codex dictation/transcription traffic through managed accounts during wrapper-launched Codex sessions.
• API capability evidence — opted-in API/ZDR routes receive daily billable checks while the router runs; status distinguishes configured access programs from verified responses. See check behavior and controls.
• Diagnostics and repair — status, live health checks, quota forecasts, JSON reports, and fix/doctor/verify commands that recover stale or damaged local state.
• Luna Reserve fallback — treats gpt-reserve as a separately metered Luna allowance, automatically falls back after a genuine Luna quota 429, and exposes the Reserve percentage through limits --json --refresh.
• Local governance — file-backed usage ledger, budget guards, account tags/weights/pause/drain policies, routing profiles, and an optional loopback bridge with bearer tokens for local OpenAI-compatible clients.
• Desktop routing (optional) — a reversible bind of the packaged Codex app plus user-level launcher helpers; official app binaries are never patched.

The four binaries

Binary	Role
codex-multi-auth	The account manager. Runs all 31 management subcommands locally (login, status, switch, forecast, rotation, fix, ...). The auth prefix is optional: codex-multi-auth login ≡ codex-multi-auth auth login.
codex-multi-auth-codex	Opt-in wrapper. Handles auth ... locally and forwards every other command to the official Codex CLI, enabling the rotation proxy for request-bearing commands.
mcodex	Convenience launcher over the wrapper, with optional --monitor and --tmux modes. No account logic of its own.
codex-multi-auth-app-launcher	User-level OS launcher routing helper (Windows shortcut, macOS wrapper app, Linux .desktop).

Install