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.
- 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
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.
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.
Terms and Usage Notice
[!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
For Humans
npm i -g codex-multi-authnpm uninstall -g @ndycode/codex-multi-auth
npm i -g codex-multi-authcodex --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 statusAny 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.
For LLM Agents
- Install global package:
npm i -g codex-multi-auth
- Run first login flow with
codex-multi-auth login - Validate state with
codex-multi-auth statusandcodex-multi-auth check - Confirm routing with
codex-multi-auth forecast --live
codex-multi-auth status
codex-multi-auth checkInstall and sign in:
npm i -g @openai/codex
npm i -g codex-multi-auth
codex-multi-auth loginIf 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 loginVerify the manager and the new account:
codex-multi-auth status
codex-multi-auth checkUse these next:
codex-multi-auth list
codex-multi-auth switch 2
codex-multi-auth forecast --liveIf 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.
To refresh one saved account without changing the active selection or manual
pin, run:
codex-multi-auth login --account <index|email|account_id> --preserve-selectionAdd --device-auth on a remote shell. The refreshed OAuth identity must match
the requested saved account or nothing is written. Refreshing the account Codex
is currently using still publishes its new tokens to the native CLI; refreshing
any other account leaves the active selection and the manual pin untouched. A
disabled account stays disabled. --account cannot be combined with --org,
which would rebind the row to a different workspace.
| 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? |
| 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? |
| 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) |
| 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? |
- 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 statussurfaces recent runtime request metrics in text output, andcodex-multi-auth report --jsonexposes the machine-readable cooldown/runtime snapshot
| Key | Action |
|---|---|
Up / Down |
Move selection |
Enter |
Select/open |
1-9 |
Quick switch |
/ |
Search |
? |
Toggle help |
Q |
Back/cancel |
| Key | Action |
|---|---|
S |
Set current account |
R |
Refresh/re-login account |
E |
Enable/disable account |
D |
Delete account |
| 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.<pid>.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 CODEX_MULTI_AUTH_DIR=<path>.
Primary config root:
~/.codex/multi-auth/settings.json- or
CODEX_MULTI_AUTH_DIR/settings.jsonwhen custom root is set
Selected runtime/environment overrides:
| Variable | Effect |
|---|---|
CODEX_MULTI_AUTH_DIR |
Override settings/accounts root |
CODEX_MULTI_AUTH_CONFIG_PATH |
Prefer this config file when it exists (also the save target when set) |
CODEX_MODE=0/1 |
Disable/enable Codex mode |
CODEX_MULTI_AUTH_FORCE_ACCOUNT=<index|email|id> |
Force one account for a single codex-multi-auth-codex run (ephemeral; requires rotation proxy) |
CODEX_MULTI_AUTH_BYPASS=1 |
Skip multi-auth intercept and forward straight to official Codex |
CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0/1 |
Opt out/in of live Responses proxy rotation for forwarded Codex CLI/app sessions |
CODEX_MULTI_AUTH_APP_ROTATION_IDLE_MS=<ms> |
Override automatic Codex app helper idle shutdown |
CODEX_MULTI_AUTH_APP_BIND_INSTALL=0/1 |
Opt out/in of packaged Codex app bind self-heal on first CLI run or rotation enable |
CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL=0/1 |
Opt out/in of routing supported app shortcuts on first CLI run or rotation enable |
CODEX_TUI_V2=0/1 |
Disable/enable TUI v2 |
CODEX_TUI_COLOR_PROFILE=truecolor|ansi256|ansi16 |
TUI color profile |
CODEX_TUI_GLYPHS=ascii|unicode|auto |
TUI glyph style |
CODEX_AUTH_BACKGROUND_RESPONSES=0/1 |
Opt in/out of stateful Responses background: true compatibility |
CODEX_AUTH_FETCH_TIMEOUT_MS=<ms> |
Request timeout override |
CODEX_AUTH_STREAM_STALL_TIMEOUT_MS=<ms> |
Stream stall timeout override |
Validate config after changes:
codex-multi-auth status
codex-multi-auth check
codex-multi-auth forecast --liveResponses background mode stays opt-in. Enable backgroundResponses in settings or CODEX_AUTH_BACKGROUND_RESPONSES=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.
Runtime rotation is enabled by default for request-bearing wrapper-launched Codex sessions. Package install scripts stay side-effect-free: npm postinstall only prints a short notice (and stays silent in CI or non-interactive installs). The first CLI run after an install self-heals supported packaged Codex app binds and user-level launcher routing when possible (recorded once in a first-run-setup.json marker under the multi-auth runtime root), while codex-multi-auth rotation enable remains the explicit repair command. codex-multi-auth rotation disable turns the setting off and removes the persistent app bind. Set CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0, CODEX_MULTI_AUTH_APP_BIND_INSTALL=0, or CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL=0 to opt out of the matching default behavior.
Installed wrappers may perform a best-effort daily npm version check during normal forwarded Codex startup. When a newer package is detected, the wrapper only prints a manual notice on an interactive TTY or when CODEX_MULTI_AUTH_DEBUG=1: npm install -g codex-multi-auth@latest. It never runs npm install or update commands for you.
The Settings menu now includes an Experimental section for staged features:
- preview-first sync into
oc-chatgpt-multi-auth - named local pool backup export with filename prompt
- refresh guard toggle and interval controls moved out of Backend Controls
These flows are intentionally non-destructive by default: sync previews before apply, destination-only accounts are preserved, and backup filename collisions fail safely.
60-second recovery
codex-multi-auth doctor --fix
codex-multi-auth check
codex-multi-auth forecast --liveIf still broken:
codex-multi-auth loginCommon symptoms
codex-multi-authunrecognized: runwhere codex-multi-authorwhich codex-multi-auth, then followdocs/troubleshooting.mdfor install checks- Switch succeeds but wrong account appears active: run
codex-multi-auth switch <index>, then restart session - Requests fail fast with a pool cooldown message: wait for the cooldown window or inspect
codex-multi-auth status - Requests fail fast after repeated upstream 5xx errors: inspect
codex-multi-auth report --jsonfor runtime traffic and cooldown details - Storage cleanup fails with
EBUSY/EPERM(Windows): runcodex-multi-auth doctor --fixto retry, or manually remove~/.codex/multi-auth/<project-key>/and re-login - OAuth callback on port
1455fails: free the port and re-runcodex-multi-auth login - Login hangs in WSL, or installing in WSL breaks a working Windows install: Windows and WSL contend for callback port
1455, and the browser opens on the Windows host either way — see Windows and WSL side by side, or usecodex-multi-auth login --device-auth, which needs no callback port - Browser launch is blocked or you are in a headless shell: prefer
codex-multi-auth login --device-auth; usecodex-multi-auth login --manualorCODEX_AUTH_NO_BROWSER=1only when you need the callback-paste fallback missing field id_token/token_expired/refresh_token_reused: re-login affected account
Diagnostics pack
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- Docs portal: docs/README.md
- Getting started: docs/getting-started.md
- Features: docs/features.md
- Configuration: docs/configuration.md
- Troubleshooting: docs/troubleshooting.md
- Commands reference: docs/reference/commands.md
- Public API contract: docs/reference/public-api.md
- Error contracts: docs/reference/error-contracts.md
- Settings reference: docs/reference/settings.md
- Storage paths: docs/reference/storage-paths.md
- Upgrade guide: docs/upgrade.md
- Privacy: docs/privacy.md
- Current stable: docs/releases/v2.9.1.md — install via
npm i -g codex-multi-auth - Previous stable: docs/releases/v2.8.3.md
- Previous stable: docs/releases/v2.8.2.md
- Previous stable: docs/releases/v2.7.1.md
- Previous stable: docs/releases/v2.7.0.md
- Previous stable: docs/releases/v2.6.0.md
- Previous stable: docs/releases/v2.5.0.md
- Previous stable: docs/releases/v2.4.0.md
- Previous stable: docs/releases/v2.3.3.md
- Previous stable: docs/releases/v2.3.2.md
- Previous stable: docs/releases/v2.3.1.md
- Previous stable: docs/releases/v2.3.0.md
- Previous stable: docs/releases/v2.2.2.md
- Previous stable: docs/releases/v2.2.1.md
- Previous stable: docs/releases/v2.2.0.md
- Previous stable: docs/releases/v2.1.12.md
- Earlier stable: docs/releases/v2.1.11.md
- Earlier stable: docs/releases/v2.1.10.md
- Earlier stable: docs/releases/v2.1.8.md
- Earlier stable: docs/releases/v2.1.7.md
- Earlier stable: docs/releases/v2.1.6.md
- Earlier stable: docs/releases/v2.1.5.md
- Earlier stable: docs/releases/v2.1.4.md
- Earlier stable: docs/releases/v2.1.3.md
- Earlier stable: docs/releases/v2.1.2.md
- Earlier stable: docs/releases/v2.1.1.md
- Earlier stable: docs/releases/v2.1.0.md
- Earlier stable: docs/releases/v1.3.2.md
- Stable archive: docs/releases/v1.3.1.md
- Full release archive: docs/README.md#release-history
- Archived prerelease: docs/releases/v0.1.0-beta.0.md
MIT License. See LICENSE.
Legal
- Not affiliated with OpenAI.
- "ChatGPT", "Codex", and "OpenAI" are trademarks of OpenAI.
- You assume responsibility for your own usage and compliance.
