Skip to content
Back to search

codex-multi-auth

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ndycode/codex-multi-auth with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ndycode/codex-multi-auth'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ndycode--codex-multi-auth/badge.svg)](/listings/ndycode--codex-multi-auth)

HTML

<a href="/listings/ndycode--codex-multi-auth"><img src="/api/listings/ndycode--codex-multi-auth/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requirements: Node.js >= 18.17, and the official Codex CLI on `PATH` (`npm i -g @openai/codex`, Homebrew, or a release binary).

npm i -g codex-multi-auth

> [!NOTE] > The legacy scoped prerelease `@ndycode/codex-multi-auth` is migration-only. Install `codex-multi-auth` for all new setups; see [docs/upgrade.md](docs/upgrade.md) to migrate.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 168 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # codex-multi-auth
  2. [![npm version](https://img.shields.io/npm/v/codex-multi-auth.svg)](https://www.npmjs.com/package/codex-multi-auth)
  3. [![npm downloads](https://img.shields.io/npm/dw/codex-multi-auth.svg)](https://www.npmjs.com/package/codex-multi-auth)
  4. [![CI](https://github.com/ndycode/codex-multi-auth/actions/workflows/ci.yml/badge.svg)](https://github.com/ndycode/codex-multi-auth/actions/workflows/ci.yml)
  5. [![MIT license](https://img.shields.io/npm/l/codex-multi-auth.svg)](LICENSE)
  6. <img width="1270" height="729" alt="codex-multi-auth terminal dashboard for Codex CLI multi-account OAuth account status" src="https://github.com/user-attachments/assets/0cecb77e-a6d3-432a-ba48-3577db0c7093" />
  7. `codex-multi-auth` is a multi-account OAuth manager for the official `@openai/codex` CLI. It keeps a named pool of ChatGPT sign-ins on your machine, lets you switch the active account, and — when you run Codex through its optional wrapper — rotates accounts across live requests through a loopback-only proxy. It never installs or shadows a `codex` binary; the official OpenAI install keeps owning that command.
  8. Use it when one Codex account is not enough: you hit rate limits or quota windows, you split work across organizations and workspaces, you want per-project account pools, or you run unattended agents that need JSON diagnostics and safe repair commands instead of one opaque auth file.
  9. Using OpenCode rather than the Codex CLI? The sibling project [`oc-codex-multi-auth`](https://github.com/ndycode/oc-codex-multi-auth) is the plugin that manages the same kind of account pool there.
  10. Refresh leases block uncoordinated OAuth refresh on lock errors or timeouts.
  11. For live re-login behavior and interrupted-refresh recovery, see the
  12. [upgrade notes](docs/upgrade.md#live-credential-reload-and-refresh-coordination).
  13. ## What it does
  14. - **Account pool** — OAuth login for multiple ChatGPT accounts, stored locally under `~/.codex/multi-auth` (files `0600`, directories `0700`), with per-project pools under `projects/<project-key>/`.
  15. - **Switching and selection** — pin an account, pick the forecast-best one, follow saved account order within customized priority tiers with sequential scheduling, or let health- and quota-aware hybrid selection rotate for you.
  16. - **Runtime rotation** — a default-on, loopback-only proxy that forwards Responses API, model-discovery, image, thread-goal, web search, Codex dictation/transcription, and native voice traffic through managed accounts during wrapper-launched Codex sessions.
  17. - **API regions** — `codex-multi-auth login --api` supports Global and US endpoints per credential. Choose **US (us.api.openai.com)** for a US-regional project; existing credentials remain Global. Each credential stays on its chosen endpoint, and Responses failover remains within the first eligible credential’s region. Regional routes use store version 2, so older builds reject them rather than silently discard their region.
  18. - **PSP API pool** — `login --api` offers Regular API, ZDR, and PSP (Private Safety Processing). ZDR approval and PSP project enrollment are operator-confirmed, never inferred from a key or successful discovery. Select `api/<model>`, `zdr/<model>`, or `psp/<model>` explicitly; failover stays within that pool and the selected region on HTTP and WebSocket connections. Global/US region selection remains separate. Choosing PSP does not enroll a project or modify provider privacy settings.
  19. - **API model metadata** — `login --api` can attach operator-declared Daybreak Red access and reasoning efforts to a selected model when discovery omits them. These declarations enable matching routes without claiming probe verification. Reasoning declarations use store version 3, so older builds cannot silently strip them.
  20. - **API capability evidence** — opted-in API/ZDR routes receive daily billable checks while the router runs; status distinguishes configured access programs from verified responses. See [check behavior and controls](docs/reference/commands.md#codex-multi-auth-check).
  21. - **Diagnostics and repair** — status, live health checks, quota forecasts, JSON reports, and `fix`/`doctor`/`verify` commands that recover stale or damaged local state.
  22. - **Luna Reserve fallback** — treats `gpt-reserve` as a separately metered Luna allowance, automatically falls back after a genuine Luna quota 429, and exposes the Reserve percentage through `limits --json --refresh`.
  23. - **Local governance** — file-backed usage ledger, budget guards, account tags/weights/pause/drain policies, routing profiles, and an optional loopback bridge with bearer tokens for local OpenAI-compatible clients.
  24. - **Desktop routing (optional)** — a reversible bind of the packaged Codex app plus user-level launcher helpers; official app binaries are never patched.
  25. ## The four binaries
  26. | Binary | Role |
  27. | --- | --- |
  28. | `codex-multi-auth` | The account manager. Runs all management subcommands locally (`login`, `status`, `web`, `switch`, `forecast`, `rotation`, `fix`, ...). The `auth` prefix is optional: `codex-multi-auth login` ≡ `codex-multi-auth auth login`. |
  29. | `codex-ma` | Short alias for `codex-multi-auth`, including the local real-time web dashboard. |
  30. | `codex-multi-auth-codex` | Opt-in wrapper. Handles `auth ...` locally and forwards every other command to the official Codex CLI, enabling the rotation proxy for request-bearing commands. |
  31. | `mcodex` | Convenience launcher over the wrapper, with optional `--monitor` and `--tmux` modes. No account logic of its own. |
  32. | `codex-multi-auth-app-launcher` | User-level OS launcher routing helper (Windows shortcut, macOS wrapper app, Linux `.desktop`). |
  33. ## Install
  34. Requirements: Node.js >= 22.19, and the official Codex CLI on `PATH` (`npm i -g @openai/codex`, Homebrew, or a release binary).
  35. ```bash
  36. npm i -g codex-multi-auth
  37. ```
  38. > [!NOTE]
  39. > The legacy scoped prerelease `@ndycode/codex-multi-auth` is migration-only. Install `codex-multi-auth` for all new setups; see [docs/upgrade.md](docs/upgrade.md) to migrate.
  40. ## Quick start (5 minutes)
  41. ```bash
  42. # 1. Sign in a ChatGPT account (browser OAuth, loopback callback on localhost:1455)
  43. codex-multi-auth login
  44. # 2. Repeat login to add more accounts, then inspect the pool
  45. codex-multi-auth status
  46. codex-ma web --no-open
  47. # 3. Probe account health and preview which account would serve next
  48. codex-multi-auth check
  49. codex-multi-auth forecast --live
  50. ```
  51. Headless or remote shell? Use `codex-multi-auth login --device-auth` — no callback port needed. Blocked browser? See [alternate login paths](docs/getting-started.md#log-in).
  52. Run Codex through the wrapper so requests rotate across the pool:
  53. ```bash
  54. codex-multi-auth-codex # interactive TUI, rotation on by default
  55. codex-multi-auth-codex exec "summarize this repo"
  56. mcodex # same wrapper, shorter name
  57. ```
  58. ## Command map
  59. `codex-multi-auth` ships 31 subcommands. The full surface — every flag, hotkey, and JSON mode — is in [docs/reference/commands.md](docs/reference/commands.md).
  60. | Group | Commands | Purpose |
  61. | --- | --- | --- |
  62. | Accounts | `login`, `list`, `status`, `switch <i>`, `unpin`, `workspace` | sign in, inspect the pool, pin or switch the active account, select or enable/disable workspaces |
  63. | Selection | `forecast`, `best`, `why-selected`, `check`, `limits`, `models` | preview, explain, and probe which account serves the next request |
  64. | Runtime | `rotation status` `enable` `disable` `bind-app` `unbind-app` `reset-runtime` `reset-rate-limits` | inspect and control live rotation and the app bind |
  65. | Repair | `fix`, `doctor`, `report`, `verify`, `verify-flagged`, `uninstall` | diagnose and repair storage, flagged accounts, and install residue; machine-readable health report |
  66. | Governance | `usage`, `budget`, `account`, `monitor`, `history`, `resets` | usage ledger, budget limits, tags/weights/pause/drain, snapshots |
  67. | Local clients | `bridge`, `integrations` | bearer tokens and client snippets for the loopback bridge |
  68. | Config | `config explain` `template`, `init-config`, `debug bundle`, `features` | effective-config report, config templates, sanitized debug bundle |
  69. Everyday examples:
  70. ```bash
  71. codex-multi-auth switch 2 # pin account #2
  72. codex-multi-auth report --live --json # full machine-readable health report
  73. codex-multi-auth fix --live --model gpt-6.1-sol # live repair probes with a chosen model
  74. codex-multi-auth doctor --fix # diagnose and apply the safest fixes
  75. codex-multi-auth usage --since 24h --by model # local usage ledger summary
  76. codex-multi-auth rotation status # is live rotation enabled?
  77. ```
  78. ## Runtime rotation, in one paragraph
  79. With rotation on (the default), request-bearing wrapper commands — `exec`, `review`, `resume`, `fork`, `app`, and the bare TUI — route through a local proxy that picks the healthiest account per request, refreshes tokens as needed, and fails over across the pool on rate limits within a bounded retry budget. The proxy listens on loopback only, authenticates its own clients with a per-process token, forwards only Responses API, model-discovery, image, thread-goal, `POST /transcribe`, `POST /alpha/search` (web search), and native voice calls (`/live` and `/realtime/calls`, plus the call's sideband WebSocket), and never writes account emails or tokens to client headers or logs. Transcription preserves the incoming multipart audio body and boundary, uses managed ChatGPT OAuth, and does not replay ambiguous audio uploads across accounts. Plain `codex` is never touched: rotation exists only inside `codex-multi-auth-codex`/`mcodex` sessions, or inside the packaged desktop app after an opt-in, reversible bind. Turn it off with `codex-multi-auth rotation disable` or `CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0`.
  80. ### Quota cache revalidation
  81. Local rate-limit blocks are valid for at most one hour. The next request then
  82. rechecks upstream, including for a hard-pinned account, so an out-of-band quota
  83. reset does not require a manual switch. A fresh upstream rejection starts a new
  84. bounded wait; this does not reset quota or spend reset credits.
  85. ## Where state lives
  86. | What | Path |
  87. | --- | --- |
  88. | Accounts, settings, quota cache, usage ledger, policies, observability | `~/.codex/multi-auth/` |
  89. | Per-project account pools | `~/.codex/multi-auth/projects/<project-key>/` |
  90. | Official Codex state (kept by the official install) | `~/.codex/` |
  91. | Override the multi-auth root | `CODEX_MULTI_AUTH_DIR=<path>` |
  92. Full path map: [docs/reference/storage-paths.md](docs/reference/storage-paths.md).
  93. ## Troubleshooting in 60 seconds
  94. ```bash
  95. codex-multi-auth doctor --fix
  96. codex-multi-auth check
  97. codex-multi-auth forecast --live
  98. ```
  99. Common symptoms — wrong active account, OAuth callback port `1455` already bound, Windows/WSL port contention, `EBUSY`/`EPERM` on Windows — are covered in [docs/troubleshooting.md](docs/troubleshooting.md).
  100. After signing in again, a running native or custom-provider router adopts the saved replacement credentials on the next authenticated request. Replacing rejected credentials clears their stale authentication block without restarting the router; account pins and independent quota limits still apply. Unchanged revoked credentials still require a new sign-in.
  101. ## Documentation
  102. | Doc | What it covers |
  103. | --- | --- |
  104. | [docs/index.md](docs/index.md) | Product overview — what it does at runtime and who needs it |
  105. | [docs/README.md](docs/README.md) | Full documentation portal and sitemap |
  106. | [docs/getting-started.md](docs/getting-started.md) | Install, first login, day-1 commands |
  107. | [docs/features.md](docs/features.md) | Feature tour |
  108. | [docs/architecture.md](docs/architecture.md) | Components, request flow, trust boundaries |
  109. | [docs/configuration.md](docs/configuration.md) | Settings and environment overrides |
  110. | [docs/reference/commands.md](docs/reference/commands.md) | Every command, flag, and hotkey |
  111. | [docs/reference/public-api.md](docs/reference/public-api.md) | Public API stability tiers and semver contract |
  112. | [docs/troubleshooting.md](docs/troubleshooting.md) | Recovery playbooks |
  113. | [docs/faq.md](docs/faq.md) | Common questions |
  114. | [docs/upgrade.md](docs/upgrade.md) | Version and legacy-package migration |
  115. | [docs/privacy.md](docs/privacy.md) | Data handling and local storage behavior |
  116. | [config/README.md](config/README.md) | Modern vs. legacy catalog templates |
  117. | [CHANGELOG.md](CHANGELOG.md) | Release history (short version) |
  118. ## Release notes
  119. - Current stable: [v2.26.2](docs/releases/v2.26.2.md) — `npm i -g codex-multi-auth`
  120. - Earlier stable lines: [v2.6.0](docs/releases/v2.6.0.md), [v2.5.0](docs/releases/v2.5.0.md)
  121. - Full release archive: [docs/README.md#release-history](docs/README.md#release-history)
  122. ## Terms and license
  123. `codex-multi-auth` uses OAuth account credentials and is intended for personal development use. It is an independent open-source project, not an official OpenAI product; you are responsible for your own usage and policy compliance, and for production or commercial workloads you should use the OpenAI Platform API. "ChatGPT", "Codex", and "OpenAI" are trademarks of OpenAI.
  124. MIT license — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.