codex-multi-auth
Advanced tools
Codex CLI multi-account OAuth manager with account switching, health checks, runtime rotation, diagnostics, and recovery tools for @openai/codex
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-authis migration-only. Usecodex-multi-authfor all new installs.
codex-multi-auth ... command familycodex-multi-auth-codex ... forwarding wrapper for official Codex CLI commands when you choose wrapper-launched sessions~/.codex/multi-auth/projects/<project-key>/... for repo-specific workflowscodex-multi-auth status / codex-multi-auth report/health, /v1/models, and /v1/responses, protected by hashed local client tokenscodex-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 now ships three distinct 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 |
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 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
npm i -g codex-multi-auth
npm uninstall -g @ndycode/codex-multi-auth
npm i -g codex-multi-auth
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.
npm i -g codex-multi-authcodex-multi-auth logincodex-multi-auth status and codex-multi-auth checkcodex-multi-auth forecast --livecodex-multi-auth status
codex-multi-auth check
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 | What it answers |
|---|---|
codex-multi-auth login | How do I add or re-open the account menu? |
codex-multi-auth status | Is the wrapper active right now? |
codex-multi-auth check | Do my saved accounts look healthy? |
| Command | What it answers |
|---|---|
codex-multi-auth list | Which accounts are saved and which one is active? |
codex-multi-auth switch <index> | How do I move to a different saved account? |
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? |
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| 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.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.jsonCODEX_MULTI_AUTH_DIR/settings.json when custom root is setSelected runtime/environment overrides:
| Variable | Effect |
|---|---|
CODEX_MULTI_AUTH_DIR | Override settings/accounts root |
CODEX_MULTI_AUTH_CONFIG_PATH | Alternate config file path |
CODEX_MODE=0/1 | Disable/enable Codex mode |
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 during install/update or rotation enable |
CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL=0/1 | Opt out/in of routing supported app shortcuts during install/update 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 --live
Responses 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. Global install/update self-heals supported packaged Codex app binds and user-level launcher routing when possible, 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:
oc-chatgpt-multi-authThese flows are intentionally non-destructive by default: sync previews before apply, destination-only accounts are preserved, and backup filename collisions fail safely.
codex-multi-auth doctor --fix
codex-multi-auth check
codex-multi-auth forecast --live
If still broken:
codex-multi-auth login
codex-multi-auth unrecognized: run where codex-multi-auth or which codex-multi-auth, then follow docs/troubleshooting.md for install checkscodex-multi-auth switch <index>, then restart sessioncodex-multi-auth statuscodex-multi-auth report --json for runtime traffic and cooldown detailsEBUSY / EPERM (Windows): run codex-multi-auth doctor --fix to retry, or manually remove ~/.codex/multi-auth/<project-key>/ and re-login1455 fails: free the port and re-run codex-multi-auth logincodex-multi-auth login --device-auth; use codex-multi-auth login --manual or CODEX_AUTH_NO_BROWSER=1 only when you need the callback-paste fallbackmissing field id_token / token_expired / refresh_token_reused: re-login affected accountcodex-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
npm i -g codex-multi-authMIT License. See LICENSE.
FAQs
Codex CLI multi-account OAuth manager with account switching, health checks, runtime rotation, diagnostics, and recovery tools for @openai/codex
The npm package codex-multi-auth receives a total of 1,116 weekly downloads. As such, codex-multi-auth popularity was classified as popular.
We found that codex-multi-auth demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Socket found 37 malicious PyPI wheels that abuse Python startup hooks to launch a Bun-powered credential stealer tied to Mini Shai-Hulud/Miasma.
Security News
RubyGems and Bundler 4.0.13 introduced an opt-in cooldown feature that delays newly published gems during dependency resolution.
Security News
pnpm 11.5 now recognizes npm staged publish approvals in release metadata, preventing those releases from being mistaken for lower-trust package publishes.