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.

[!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

• Install global package:

• npm i -g codex-multi-auth

• Run first login flow with codex-multi-auth login

• Validate state with codex-multi-auth status and codex-multi-auth check

• 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 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 runti