npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

codex-multi-auth

v2.1.10

Published

Codex CLI multi-account OAuth manager with account switching, health checks, runtime rotation, diagnostics, and recovery tools for @openai/codex

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

ndycodendycode

Keywords

openaicodexcodex-clicodex-authcodex-multi-accountchatgptoauthoauth2pkcemulti-accountaccount-switchingoauth-managerruntime-rotationresponses-apilocal-proxyquota-managementdiagnosticsfault-toleranceterminal-uicli-tooltypescriptnodejsdeveloper-toolsauthenticationaccount-healthrecovery-toolsproject-scoped-storage

Readme

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

npm version npm downloads CI MIT license

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:

| 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

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

| 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? |

Daily use

| 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? |

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.3-codex | 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 | | 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>.

Configuration

Primary config root:

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

Selected 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.

Experimental Settings Highlights

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.

Troubleshooting

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 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 --json for runtime traffic and cooldown details
  • Storage cleanup fails with EBUSY / EPERM (Windows): run codex-multi-auth doctor --fix to retry, or manually remove ~/.codex/multi-auth/<project-key>/ and re-login
  • OAuth callback on port 1455 fails: free the port and re-run codex-multi-auth login
  • Browser launch is blocked or you are in a headless shell: prefer codex-multi-auth login --device-auth; use codex-multi-auth login --manual or CODEX_AUTH_NO_BROWSER=1 only when you need the callback-paste fallback
  • missing field id_token / token_expired / refresh_token_reused: re-login affected account
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

Documentation

Release Notes

License

MIT License. See LICENSE.

  • Not affiliated with OpenAI.
  • "ChatGPT", "Codex", and "OpenAI" are trademarks of OpenAI.
  • You assume responsibility for your own usage and compliance.