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

The single auth file problem codex-multi-auth targets

The official Codex CLI keeps one ChatGPT login. When that account hits a quota ceiling, or when a token goes stale, the user has no local view of what happened and no second identity to fall back on. codex-multi-auth exists to make that state explicit: instead of one opaque auth file, the README describes a named account pool, deterministic switching, health-aware selection and JSON diagnostics that other tools can read.

The audience is narrow and the README says so. This is for personal development workflows on a developer machine, where credentials stay local. The project states plainly that it is an independent open-source project, not an official OpenAI product, and that production or commercial workloads belong on the OpenAI Platform API. That boundary matters more than any feature list: if you are building a service, this is the wrong layer.

Four binaries and where the official codex command stays

The package installs four global binaries and deliberately does not publish a global codex. The primary one, codex-multi-auth, is the account manager and accepts bare subcommands such as login, status, switch, forecast and rotation status. codex-multi-auth-codex is an optional wrapper that handles auth ... locally and forwards everything else to the official CLI. mcodex is a convenience launcher over that wrapper with optional --monitor and --tmux modes. codex-multi-auth-app-launcher is a desktop helper for user-level shortcuts and wrapper apps.

That split is the architectural decision worth noticing. Account management lives in one command family, and the official codex binary keeps owning its own name. The README is explicit that any official install path is fine as long as codex is on PATH, whether that is npm i -g @openai/codex, brew install --cask codex, or a release binary. If you never want a wrapper in the path, you can use the manager alone and leave Codex untouched.

State is project-scoped, stored under ~/.codex/multi-auth/projects/<project-key>/..., so different repositories can hold different account selections. The runtime side is a loopback-only Responses proxy that the README describes as default-on for forwarded Codex sessions, with an optional local bridge exposing /health, /v1/models and /v1/responses behind hashed local client tokens.

Installing codex-multi-auth and signing in the first account

The README gives a standard global install. If the official CLI is not present yet, install both packages; if you already have Codex from Homebrew or a release binary, install only the manager. The command below covers the first case.

npm i -g @openai/codex
npm i -g codex-multi-auth
codex-multi-auth login

login starts the ChatGPT OAuth flow. The README notes that if browser launch is blocked you should use the alternate login paths in docs/getting-started.md, and that remote or headless shells should prefer device auth:

codex-multi-auth login --device-auth

After login, confirm that the manager sees the account and that the official binary is still reachable. The README uses these three commands as the wiring check.

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

What you should see is a version string from the official CLI, a separate version string from the manager, and a status view listing your saved accounts. From there the README suggests listing accounts, switching by index, and asking for a live quota forecast.

codex-multi-auth list
codex-multi-auth switch 2
codex-multi-auth forecast --live

switch 2 selects the second saved account. forecast --live is the one command in this sequence that reaches out to check quota rather than reading local state, so expect it to be slower than the others.

Health checks, forecasting and recovery are the real product

Switching accounts is a small feature. The parts that justify a separate tool are the operational commands: forecast, report, fix, doctor, verify, monitor and rotation. The README groups them under operational confidence, and the underlying behaviour includes health-aware account selection, quota forecasting, automatic failover and flagged-account recovery.

For automation, status and report expose runtime counters, budget and cooldown state, and multi-auth probe visibility. That is the difference between a shell script that rewrites an auth file and a manager that can tell you which account is cooling down and why. The README also mentions a local usage ledger, budget guards, account policy controls and routing profiles, plus session affinity, live account sync, proactive refresh and preemptive quota deferral controls.

Two honest caveats sit in that list. First, forecasting is a prediction, not a guarantee, and the README does not document how accurate the live forecast is. Second, the feature surface is large for a personal tool: routing profiles, policy controls and budget guards are configuration you have to understand before they help you, and the README does not walk through tuning them.

Where codex-multi-auth is the wrong tool

The clearest limitation is stated by the project itself. The terms notice says the package is intended for personal development use, that you are responsible for your own usage and policy compliance, and that production or commercial workloads should use the OpenAI Platform API. Rotating personal ChatGPT accounts to raise throughput is not what this is for, and the README does not pretend otherwise.

There are mechanical limits too. The runtime rotation proxy is loopback-only, so it helps forwarded Codex sessions on the same machine and nothing else; there is no documented way to run it as a shared service. The forwarding wrapper is opt-in, which means a session started with plain codex does not get rotation at all. And the manager depends on the official CLI staying where it is: the README treats codex as owned by the OpenAI install path, so anything that replaces or relocates that binary is outside the design.

One more gap worth flagging: the README does not document rollback of the optional packaged Codex app bind, even though it describes those bind and launcher helpers as reversible. If you enable them, you are trusting the word reversible without a documented procedure.

How this differs from writing your own account switcher

The obvious alternative is a shell script that copies a saved auth file into place before each Codex run. That approach is a few lines and has no dependencies. The difference is what happens after the copy: a script has no concept of account health, no quota forecast, no cooldown state, and no way to fail over mid-session, because the official CLI reads one credential at startup.

codex-multi-auth moves the decision into a proxy and a manager. The default-on loopback Responses proxy can rotate accounts inside a forwarded session, and the manager keeps per-account counters and health so the choice is not blind. The cost is a Node process in the path, a wrapper you have to remember to use, and a state directory under ~/.codex/multi-auth. If your problem is only I have two accounts and I switch weekly, the script is simpler. If your problem is account one keeps running dry mid-task, the manager is doing work the script cannot.

Maintenance, upgrade cost and the MIT licence

The repository is not archived, and the last push was on 2026-09-08, which is six days before this article. The release history shows v2.12.0 on 2026-09-04, v2.13.0 and v2.14.0 both on 2026-09-08, so the project is shipping frequently right now. Frequent releases on a tool that sits in your authentication path also mean frequent upgrades, and the README points to a documented upgrade path plus release notes, so read those before bumping a global install.

The package is MIT licensed, which is permissive for local and internal use. It is still worth separating two things: the licence covers the code, and the terms notice covers the credentials. The README states that you are responsible for your own usage and policy compliance, and that this is not an official OpenAI product. Nothing here is legal advice, and the OAuth flow means your ChatGPT account terms apply regardless of what the MIT licence says about the software.

One migration detail from the README: the legacy scoped prerelease package @ndycode/codex-multi-auth is migration-only. New installs should use the unscoped codex-multi-auth name, and the README gives an explicit uninstall-then-install sequence for anyone moving off it.

Editorial conclusion

Adopt codex-multi-auth if you run the official Codex CLI on your own machine and keep hitting single-account quota limits; skip it if you need production or commercial throughput, because the README points those workloads at the OpenAI Platform API instead. Before trusting it, verify two things on your own setup: that codex --version still resolves to the official binary after install, and that codex-multi-auth status reports the account you expect after your first login.

Frequently asked questions

Official sources

1. License: MIT
2. ndycode/codex-multi-auth on GitHub
3. Project website
4. README
5. Releases