codex-multi-auth: multi-account OAuth for the official Codex CLI

codex-multi-auth is a multi-account OAuth manager for the official @openai/codex CLI. It gives Codex CLI users explicit ChatGPT account login, account switching, health checks, local diagnostics, project-scoped storage, and default-on runtime Responses rotation without taking over the official codex binary. Use codex-multi-auth ... for account management, or codex-multi-auth-codex ... only when you intentionally want the optional forwarding wrapper.

Use it when you need a local Codex CLI multi-account workflow with visible account state, safer recovery commands, and a loopback-only runtime rotation proxy for request-bearing forwarded Codex sessions.

[!NOTE] Legacy scoped prerelease package @ndycode/codex-multi-auth is migration-only. Use codex-multi-auth for all new installs.

What You Get

• Codex CLI multi-account OAuth management with a dedicated codex-multi-auth ... command family
• Explicit ChatGPT account login, saved-account listing, account switching, health checks, and diagnostics
• Optional codex-multi-auth-codex ... forwarding wrapper for official Codex CLI commands when you choose wrapper-launched sessions
• Health-aware account selection, quota forecasting, automatic failover, and flagged-account recovery
• Project-scoped account storage under ~/.codex/multi-auth/projects/<project-key>/... for repo-specific workflows
• Interactive terminal dashboard for account actions, settings, search, and hotkeys
• Forecast, report, fix, doctor, verify, monitor, and rotation commands for operational confidence
• Local usage ledger, budget guards, account policy controls, routing profiles, and model/account capability views
• Runtime counters, budget/cooldown state, and multi-auth probe visibility in codex-multi-auth status / codex-multi-auth report
• Default-on loopback Responses proxy for live account rotation inside forwarded Codex CLI/app sessions
• Optional loopback-only local bridge for /health, /v1/models, and /v1/responses, protected by hashed local client tokens
• Reversible packaged Codex app bind and user-level launcher routing helpers that do not patch official app binaries
• Session affinity, live account sync, proactive refresh, and preemptive quota deferral controls
• Codex-oriented request/prompt compatibility with strict runtime handling and documented error contracts
• Stable docs for install, configuration, troubleshooting, upgrade, public API, storage paths, and release notes

Why Developers Use It

codex-multi-auth makes local Codex account state visible and recoverable. Instead of one opaque auth file, you get a named account pool, deterministic account switching, health-aware selection, JSON diagnostics for automation, and safe repair commands for stale or damaged local state. The architecture is designed for personal development workflows: credentials stay local, runtime rotation is loopback-only, and official Codex install paths keep owning the codex command.

Current Architecture At A Glance

codex-multi-auth now ships three distinct global binaries:

The package does not publish a global codex binary. Keep codex owned by the official OpenAI install path and use codex-multi-auth-codex ... only when you intentionally want this package's forwarding wrapper.

[!CAUTION] This project uses OAuth account credentials and is intended for personal development use.

By using this package, you acknowledge:

• This is an independent open-source project, not an official OpenAI product
• You are responsible for your own usage and policy compliance
• For production/commercial workloads, use the OpenAI Platform API

Installation

Option A: Standard install

npm i -g codex-multi-auth

Option B: Migrate from legacy scoped prerelease

npm uninstall -g @ndycode/codex-multi-auth
npm i -g codex-multi-auth

Option C: Verify wiring

codex --version confirms the official Codex CLI is reachable. codex-multi-auth --version confirms the installed manager package version. codex-multi-auth-codex --version is the optional forwarding wrapper entrypoint.

codex --version
codex-multi-auth --version
codex-multi-auth status

Any official install path is fine as long as codex is on PATH: npm i -g @openai/codex, brew install --cask codex, or an official release binary.

Step-by-step

1. Install global package:
   • npm i -g codex-multi-auth
2. Run first login flow with codex-multi-auth login
3. Validate state with codex-multi-auth status and codex-multi-auth check
4. Confirm routing with codex-multi-auth forecast --live

Verification

codex-multi-auth status
codex-multi-auth check

Quick Start

Install and sign in:

npm i -g @openai/codex
npm i -g codex-multi-auth
codex-multi-auth login

If you already installed the official native CLI via Homebrew or a release binary, you only need:

npm i -g codex-multi-auth
codex-multi-auth login

Verify the manager and the new account:

codex-multi-auth status
codex-multi-auth check

Use these next:

codex-multi-auth list
codex-multi-auth switch 2
codex-multi-auth forecast --live

If browser launch is blocked, use the alternate login paths in docs/getting-started.md. For remote or headless shells, prefer codex-multi-auth login --device-auth.

Command Toolkit

Start here

Daily use

Repair

Advanced

Reliability behavior

• whole-pool replay is disabled by default when every account is rate-limited
• active requests use a bounded outbound request budget so one prompt cannot walk the full pool indefinitely
• repeated cross-account 5xx bursts trigger a short cooldown instead of continuing aggressive rotation
• proactive refresh is staggered to reduce background refresh bursts
• codex-multi-auth status surfaces recent runtime request metrics in text output, and codex-multi-auth report --json exposes the machine-readable cooldown/runtime snapshot

Dashboard Hotkeys

Main dashboard

Account details

Storage Paths