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 ships four global binaries:

| Binary | Purpose | | --- | --- | | codex-multi-auth | Primary account manager; accepts bare auth subcommands such as login, status, switch, forecast, and rotation status | | codex-multi-auth-codex | Optional wrapper that handles auth ... locally and forwards every other command to the official Codex CLI | | mcodex | Convenience launcher over codex-multi-auth-codex with optional --monitor and --tmux modes | | codex-multi-auth-app-launcher | Optional desktop launcher helper for supported user-level shortcuts and wrapper apps |

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

Installation

npm i -g codex-multi-auth

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

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

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

| Command | What it answers | | --- | --- | | codex-multi-auth login | How do I add or re-open the account menu? | | codex-multi-auth status | What does my account pool, pin, and runtime metrics look like? (list is the same output) | | codex-multi-auth check | Do live health probes against my saved accounts succeed? |

Daily use

| Command | What it answers | | --- | --- | | codex-multi-auth list | Alias of status — full account/runtime dump | | codex-multi-auth switch <index> | How do I pin a different saved account for runtime routing? | | codex-multi-auth unpin | How do I clear a manual pin and resume hybrid rotation? | | codex-multi-auth workspace <account> [workspace] | How do I list or set an account's active workspace? | | codex-multi-auth best --live | How do I switch to the forecast-best account (clears any pin)? | | codex-multi-auth-codex --account <index\|email\|id> | How do I force one account for a single wrapper session without changing my default? | | codex-multi-auth forecast --live | Which account looks best for the next session? |

Repair

| Command | What it answers | | --- | --- | | codex-multi-auth verify-flagged | Can any previously flagged account be restored? | | codex-multi-auth verify --paths | Do my storage path chain and sandbox probes still pass self-test? | | codex-multi-auth fix --dry-run | What safe storage or account repairs are available? | | codex-multi-auth doctor --fix | Can the CLI diagnose and apply the safest fixes now? | | codex-multi-auth uninstall | Remove residual artifacts (run BEFORE npm uninstall; npm@7+ no longer fires preuninstall) |

Advanced

| Command | What it answers | | --- | --- | | codex-multi-auth report --live --json | How do I get the full machine-readable health report? | | codex-multi-auth fix --live --model gpt-5.5 | How do I run live repair probes with a chosen model? | | codex-multi-auth why-selected --json | Which account does the selector pick now, and why? | | codex-multi-auth usage --since 24h --by project | What local usage has been recorded recently? | | codex-multi-auth monitor --json | What is the combined usage, policy, quota, runtime, and project state? | | codex-multi-auth bridge token create --label local-client | How do I create a local bridge bearer token? | | codex-multi-auth integrations --kind python | How do I generate local bridge client snippets? | | codex-multi-auth rotation status | Is live runtime account rotation enabled for forwarded Codex sessions? |

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

| Key | Action | | --- | --- | | Up / Down | Move selection | | Enter | Select/open | | 1-9 | Quick switch | | / | Search | | ? | Toggle help | | Q | Back/cancel |

Account details

| Key | Action | | --- | --- | | S | Set current account | | R | Refresh/re-login account | | E | Enable/disable account | | D | Delete account |

Storage Paths

| File | Default path | | --- | --- | | Settings | ~/.codex/multi-auth/settings.json | | Accounts | ~/.codex/multi-auth/openai-codex-accounts.json | | Flagged accounts | ~/.codex/multi-auth/openai-codex-flagged-accounts.json | | Quota cache | ~/.codex/multi-auth/quota-cache.json | | Runtime observability | ~/.codex/multi-auth/runtime-observability.json | | Usage ledger | ~/.codex/multi-auth/usage/usage-ledger.jsonl | | Account policies | ~/.codex/multi-auth/account-policies.json | | Routing profiles | ~/.codex/multi-auth/routing-profiles.json | | Budget guards | ~/.codex/multi-auth/budget-guards.json | | Local client tokens | ~/.codex/multi-auth/local-client-tokens.json | | Runtime app helper status | ~/.codex/multi-auth/runtime-rotation-app-helper.json | | Runtime app helper owner metadata | ~/.codex/multi-auth/runtime-rotation-app-helper-owner.<pid>.json | | Persistent app bind state/logs | ~/.codex/multi-auth/app-bind/ | | Logs | ~/.codex/multi-auth/logs/codex-plugin/ | | Per-project accounts | ~/.codex/multi-auth/projects/<project-key>/openai-codex-accounts.json |

Override root with CODEXMULTIAUTH_DIR=<path>.

Configuration

Primary config root:

• ~/.codex/multi-auth/settings.json
• or CODEXMULTIAUTH_DIR/settings.json when custom root is set

| Variable | Effect | | --- | --- | | CODEXMULTIAUTH_DIR | Override settings/accounts root | | CODEXMULTIAUTHCONFIGPATH | Prefer this config file when it exists (also the save target when set) | | CODEX_MODE=0/1 | Disable/enable Codex mode | | CODEXMULTIAUTHFORCEACCOUNT=<index\|email\|id> | Force one account for a single codex-multi-auth-codex run (ephemeral; requires rotation proxy) | | CODEXMULTIAUTH_BYPASS=1 | Skip multi-auth intercept and forward straight to official Codex | | CODEXMULTIAUTHRUNTIMEROTATION_PROXY=0/1 | Opt out/in of live Responses proxy rotation for forwarded Codex CLI/app sessions | | CODEXMULTIAUTHAPPROTATIONIDLEMS=<ms> | Override automatic Codex app helper idle shutdown | | CODEXMULTIAUTHAPPBIND_INSTALL=0/1 | Opt out/in of packaged Codex app bind self-heal on first CLI run or rotation enable | | CODEXMULTIAUTHAPPLAUNCHER_INSTALL=0/1 | Opt out/in of routing supported app shortcuts on first CLI run or rotation enable | | CODEXTUIV2=0/1 | Disable/enable TUI v2 | | CODEXTUICOLOR_PROFILE=truecolor\|ansi256\|ansi16 | TUI color profile | | CODEXTUIGLYPHS=ascii\|unicode\|auto | TUI glyph style | | CODEXAUTHBACKGROUND_RESPONSES=0/1 | Opt in/out of stateful Responses background: true compatibility | | CODEXAUTHFETCHTIMEOUTMS=<ms> | Request timeout override | | CODEXAUTHSTREAMSTALLTIMEOUT_MS=<ms> | Stream stall timeout override |

Validate config after changes:

codex-multi-auth status
codex-multi-auth check
codex-multi-auth forecast --live

Responses background mode stays opt-in. Enable backgroundResponses in settings or CODEXAUTHBACKGROUNDRESPONSES=1 only for callers that intentionally send background: true, because those requests switch from stateless store=false routing to stateful store=true. See docs/upgrade.md for rollout guidance.

codex-multi-auth doctor --fix
codex-multi-auth check
codex-multi-auth forecast --live

codex-multi-auth login

codex-multi-auth list
codex-multi-auth status
codex-multi-auth check
codex-multi-auth verify-flagged --json
codex-multi-auth forecast --live
codex-multi-auth fix --dry-run
codex-multi-auth report --live --json
codex-multi-auth doctor --json