codex-multi-auth 2.17.0 → 2.17.3

package/README.md

@@ -1,484 +1,142 @@
-# codex-multi-auth: multi-account OAuth for the official Codex CLI
-
-[![npm version](https://img.shields.io/npm/v/codex-multi-auth.svg)](https://www.npmjs.com/package/codex-multi-auth)
-[![npm downloads](https://img.shields.io/npm/dw/codex-multi-auth.svg)](https://www.npmjs.com/package/codex-multi-auth)
-[![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)
-[![MIT license](https://img.shields.io/npm/l/codex-multi-auth.svg)](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.
-
-<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" />
-
-
-
-> [!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
-- [Image generation/edit transport](docs/reference/image-routes.md) through the same authenticated runtime proxy
-- [Built-in image_gen provider compatibility](docs/reference/imagegen-provider-compatibility.md) through the same authenticated runtime proxy
-- 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
-
----
-
-## Optional automatic subscription priming
-
-Run `codex-multi-auth account auto-prime <index> on` to opt an account into
-periodic first-use checks by the running CLI/app router (every 15 minutes).
-It completes a tiny response only for an unused personal subscription and
-consumes subscription quota. The default is off; use `off` to disable it.
-Manual `check` still needs `--prime`. See the [command reference](docs/reference/commands.md).
-
-## 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.
-
-With runtime rotation enabled, interactive `mcodex resume` lists saved CLI and desktop sessions across providers in the current directory. Use `mcodex resume --all` to include other directories, or `-C <directory>` to change the project scope. Select a session to resume it through multi-auth; Escape cancels. Discovery uses the official local Codex app-server and does not rewrite session metadata. Desktop and CLI must use the same `CODEX_HOME` for shared history.
-
-Explicit session IDs, `--last`, remote connections, non-interactive invocations, and the in-session `/resume` command retain native Codex behavior. The cross-provider picker requires an official Codex version supporting the app-server `thread/list` API.
-
----
-
-<details open>
-<summary><b>Terms and Usage Notice</b></summary>
-
-> [!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
-
-</details>
-
----
-
-## Installation
-
-<details open>
-<summary><b>For Humans</b></summary>
-
-### Option A: Standard install
-
-```bash
-npm i -g codex-multi-auth
-```
-
-### Option B: Migrate from legacy scoped prerelease
-
-```bash
-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.
-
-```bash
-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.
-
-</details>
-
-<details>
-<summary><b>For LLM Agents</b></summary>
-
-### 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
-
-```bash
-codex-multi-auth status
-codex-multi-auth check
-```
-
-</details>
-
----
-
-## Quick Start
-
-Install and sign in:
-
-```bash
-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:
-
-```bash
-npm i -g codex-multi-auth
-codex-multi-auth login
-```
-
-Verify the manager and the new account:
-
-```bash
-codex-multi-auth status
-codex-multi-auth check
-```
-
-Use these next:
-
-```bash
-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](docs/getting-started.md#alternate-login-paths).
-For remote or headless shells, prefer `codex-multi-auth login --device-auth`.
-To refresh one saved account without changing the active selection or manual
-pin, run:
-
-```bash
-codex-multi-auth login --account <index|email|account_id> --preserve-selection
-```
-
-Add `--device-auth` on a remote shell. The refreshed OAuth identity must match
-the requested saved account or nothing is written. Refreshing the account Codex
-is currently using still publishes its new tokens to the native CLI; refreshing
-any other account leaves the active selection and the manual pin untouched. A
-disabled account stays disabled. `--account` cannot be combined with `--org`,
-which would rebind the row to a different workspace.
-
----
-
-## 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 limits --json [--refresh]` | How do I read account quota windows without parsing internal cache files or terminal text? |
-| `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 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.<pid>.json` |
-| Runtime app helper owner metadata | `~/.codex/multi-auth/runtime-rotation-app-helper-owner.<pid>.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` | Prefer this config file when it exists (also the save target when set) |
-| `CODEX_MODE=0/1` | Disable/enable Codex mode |
-| `CODEX_MULTI_AUTH_FORCE_ACCOUNT=<index\|email\|id>` | Force one account for a single `codex-multi-auth-codex` run (ephemeral; requires rotation proxy) |
-| `CODEX_MULTI_AUTH_BYPASS=1` | Skip multi-auth intercept and forward straight to official Codex |
-| `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_RUNTIME_PROXY_UPSTREAM_BASE_URL=http://127.0.0.1:<port>/<path>` | Route the runtime rotation proxy through an explicit loopback HTTP upstream; requires an explicit port and a numeric loopback host (`127.0.0.0/8` or `[::1]`), and rejects credentials, query strings, fragments, HTTPS, and every other host |
-| `CODEX_MULTI_AUTH_MODEL_CAPACITY_RETRY_MS=<ms>` | Wall-clock ceiling on how long one request waits out a "selected model is at capacity" response before giving up (default 600000, max 3600000, `0` disables) |
-| `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 on first CLI run or rotation enable |
-| `CODEX_MULTI_AUTH_APP_LAUNCHER_INSTALL=0/1` | Opt out/in of routing supported app shortcuts on first CLI run 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:
-
-```bash
-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](docs/upgrade.md) for rollout guidance.
-
-Runtime rotation is enabled by default for request-bearing wrapper-launched Codex sessions. Package install scripts stay side-effect-free: npm postinstall only prints a short notice (and stays silent in CI or non-interactive installs). The first CLI run after an install self-heals supported packaged Codex app binds and user-level launcher routing when possible (recorded once in a `first-run-setup.json` marker under the multi-auth runtime root), 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.
-
-Advanced local proxy chains can set `CODEX_MULTI_AUTH_RUNTIME_PROXY_UPSTREAM_BASE_URL` for one wrapper process. The wrapper passes that URL to both the shadow-runtime and interactive-helper rotation paths and fails closed if the configured upstream is invalid or unavailable; it never falls back silently to the direct backend while an explicit upstream is required. Because the request that reaches the upstream carries the managed OAuth bearer token, the host must be a numeric loopback literal: a name such as `localhost` is rejected, since a hosts-file entry can point it at a routable address. "Fails closed" also covers the case where runtime rotation itself is off (`CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0`, `CODEX_MULTI_AUTH_BYPASS=1`, or the setting disabled): a request-bearing invocation exits non-zero rather than bypassing the configured upstream. Subcommands that make no backend requests still run normally.
-
-When the backend answers that the selected model is at capacity, the runtime proxy waits and re-sends the request instead of burning the pool. Capacity is a property of the model, not of an account, so rotating spends the transient budget against accounts that all fail identically and the request ends as a 503 within seconds. The wait backs off (2s, 5s, 15s, 30s, then 60s), honors an upstream `retry-after` when one is sent, and stops at a wall-clock deadline set by `CODEX_MULTI_AUTH_MODEL_CAPACITY_RETRY_MS` (10 minutes by default, 1 hour maximum). Set that variable to `0` to restore the previous rotate-and-fail behavior. The responding account is left completely unpenalized: its pool token is refunded and it is never marked rate limited or cooled down, so selection runs normally on the next pass and may pick any healthy account. The wait is abandoned if the client disconnects, so no further upstream request is sent for a response nobody is reading. See [#689](https://github.com/ndycode/codex-multi-auth/issues/689).
-
-Trust boundary: the loopback check bounds exposure to the local machine, and nothing more. It does not authenticate the process listening on that port, and plaintext HTTP is what a local inspection proxy needs, so any process that can bind the port you name receives the managed bearer token in cleartext. Set this variable only on a machine where you trust every local process that can bind a loopback port, and only for as long as you need the chain.
-
-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
-- context budget guard: pause a session before it hits the model's context window, with independently configurable soft/hard thresholds (default 65% / 69%) — ships disabled; see [Context Budget Guard](docs/features.md#context-budget-guard-experimental)
-
-These flows are intentionally non-destructive by default: sync previews before apply, destination-only accounts are preserved, and backup filename collisions fail safely.
-
----
-
-## Troubleshooting
-
-<details open>
-<summary><b>60-second recovery</b></summary>
-
-```bash
-codex-multi-auth doctor --fix
-codex-multi-auth check
-codex-multi-auth forecast --live
-```
-
-If still broken:
-
-```bash
-codex-multi-auth login
-```
-
-</details>
-
-<details>
-<summary><b>Common symptoms</b></summary>
-
-- `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`
-- Login hangs in WSL, or installing in WSL breaks a working Windows install: Windows and WSL contend for callback port `1455`, and the browser opens on the Windows host either way — see [Windows and WSL side by side](docs/troubleshooting.md#windows-and-wsl-side-by-side), or use `codex-multi-auth login --device-auth`, which needs no callback port
-- 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
-
-</details>
-
-<details>
-<summary><b>Diagnostics pack</b></summary>
-
-```bash
-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
-```
-
-</details>
-
----
-
-## Documentation
-
-- Docs portal: [docs/README.md](docs/README.md)
-- Getting started: [docs/getting-started.md](docs/getting-started.md)
-- Features: [docs/features.md](docs/features.md)
-- Configuration: [docs/configuration.md](docs/configuration.md)
-- Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)
-- Commands reference: [docs/reference/commands.md](docs/reference/commands.md)
-- Public API contract: [docs/reference/public-api.md](docs/reference/public-api.md)
-- Error contracts: [docs/reference/error-contracts.md](docs/reference/error-contracts.md)
-- Settings reference: [docs/reference/settings.md](docs/reference/settings.md)
-- Storage paths: [docs/reference/storage-paths.md](docs/reference/storage-paths.md)
-- Upgrade guide: [docs/upgrade.md](docs/upgrade.md)
-- Privacy: [docs/privacy.md](docs/privacy.md)
-
----
-
-## Release Notes
-
-- Current stable: [docs/releases/v2.17.0.md](docs/releases/v2.17.0.md) — install via `npm i -g codex-multi-auth`
-- Previous stable: [docs/releases/v2.8.3.md](docs/releases/v2.8.3.md)
-- Previous stable: [docs/releases/v2.8.2.md](docs/releases/v2.8.2.md)
-- Previous stable: [docs/releases/v2.7.1.md](docs/releases/v2.7.1.md)
-- Previous stable: [docs/releases/v2.7.0.md](docs/releases/v2.7.0.md)
-- Previous stable: [docs/releases/v2.6.0.md](docs/releases/v2.6.0.md)
-- Previous stable: [docs/releases/v2.5.0.md](docs/releases/v2.5.0.md)
-- Previous stable: [docs/releases/v2.4.0.md](docs/releases/v2.4.0.md)
-- Previous stable: [docs/releases/v2.3.3.md](docs/releases/v2.3.3.md)
-- Previous stable: [docs/releases/v2.3.2.md](docs/releases/v2.3.2.md)
-- Previous stable: [docs/releases/v2.3.1.md](docs/releases/v2.3.1.md)
-- Previous stable: [docs/releases/v2.3.0.md](docs/releases/v2.3.0.md)
-- Previous stable: [docs/releases/v2.2.2.md](docs/releases/v2.2.2.md)
-- Previous stable: [docs/releases/v2.2.1.md](docs/releases/v2.2.1.md)
-- Previous stable: [docs/releases/v2.2.0.md](docs/releases/v2.2.0.md)
-- Previous stable: [docs/releases/v2.1.12.md](docs/releases/v2.1.12.md)
-- Earlier stable: [docs/releases/v2.1.11.md](docs/releases/v2.1.11.md)
-- Earlier stable: [docs/releases/v2.1.10.md](docs/releases/v2.1.10.md)
-- Earlier stable: [docs/releases/v2.1.8.md](docs/releases/v2.1.8.md)
-- Earlier stable: [docs/releases/v2.1.7.md](docs/releases/v2.1.7.md)
-- Earlier stable: [docs/releases/v2.1.6.md](docs/releases/v2.1.6.md)
-- Earlier stable: [docs/releases/v2.1.5.md](docs/releases/v2.1.5.md)
-- Earlier stable: [docs/releases/v2.1.4.md](docs/releases/v2.1.4.md)
-- Earlier stable: [docs/releases/v2.1.3.md](docs/releases/v2.1.3.md)
-- Earlier stable: [docs/releases/v2.1.2.md](docs/releases/v2.1.2.md)
-- Earlier stable: [docs/releases/v2.1.1.md](docs/releases/v2.1.1.md)
-- Earlier stable: [docs/releases/v2.1.0.md](docs/releases/v2.1.0.md)
-- Earlier stable: [docs/releases/v1.3.2.md](docs/releases/v1.3.2.md)
-- Stable archive: [docs/releases/v1.3.1.md](docs/releases/v1.3.1.md)
-- Full release archive: [docs/README.md#release-history](docs/README.md#release-history)
-- Archived prerelease: [docs/releases/v0.1.0-beta.0.md](docs/releases/v0.1.0-beta.0.md)
-
-## License
-
-MIT License. See [LICENSE](LICENSE).
-
-<details>
-<summary><b>Legal</b></summary>
-
-- Not affiliated with OpenAI.
-- "ChatGPT", "Codex", and "OpenAI" are trademarks of OpenAI.
-- You assume responsibility for your own usage and compliance.
-
-</details>
-
-### Optional native desktop binding
-
-Native desktop features such as Remote Control pairing need the real desktop
-account identity. Use `codex-multi-auth rotation bind-app --native` to preserve
-that login while routing inference through managed accounts. Add
-`--catalog-account <index>` to use one account's live model catalog. This mode
-requires file-backed desktop credentials; see the [rotation command reference](docs/reference/commands.md#native-provider-binding-opt-in)
-for setup, limitations, and rollback.
+# codex-multi-auth
+
+[![npm version](https://img.shields.io/npm/v/codex-multi-auth.svg)](https://www.npmjs.com/package/codex-multi-auth)
+[![npm downloads](https://img.shields.io/npm/dw/codex-multi-auth.svg)](https://www.npmjs.com/package/codex-multi-auth)
+[![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)
+[![MIT license](https://img.shields.io/npm/l/codex-multi-auth.svg)](LICENSE)
+
+`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.
+
+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.
+
+## What it does
+
+- **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>/`.
+- **Switching and selection** — pin an account, pick the forecast-best one, or let health- and quota-aware hybrid selection rotate for you.
+- **Runtime rotation** — a default-on, loopback-only proxy that forwards Responses API and model-discovery traffic through the best available account during wrapper-launched Codex sessions.
+- **Diagnostics and repair** — status, live health checks, quota forecasts, JSON reports, and `fix`/`doctor`/`verify` commands that recover stale or damaged local state.
+- **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.
+- **Desktop routing (optional)** — a reversible bind of the packaged Codex app plus user-level launcher helpers; official app binaries are never patched.
+
+## The four binaries
+
+| Binary | Role |
+| --- | --- |
+| `codex-multi-auth` | The account manager. Runs all 31 management subcommands locally (`login`, `status`, `switch`, `forecast`, `rotation`, `fix`, ...). The `auth` prefix is optional: `codex-multi-auth login` ≡ `codex-multi-auth auth login`. |
+| `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. |
+| `mcodex` | Convenience launcher over the wrapper, with optional `--monitor` and `--tmux` modes. No account logic of its own. |
+| `codex-multi-auth-app-launcher` | User-level OS launcher routing helper (Windows shortcut, macOS wrapper app, Linux `.desktop`). |
+
+## Install
+
+Requirements: Node.js >= 18.17, and the official Codex CLI on `PATH` (`npm i -g @openai/codex`, Homebrew, or a release binary).
+
+```bash
+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.
+
+## Quick start (5 minutes)
+
+```bash
+# 1. Sign in a ChatGPT account (browser OAuth, loopback callback on localhost:1455)
+codex-multi-auth login
+
+# 2. Repeat login to add more accounts, then inspect the pool
+codex-multi-auth status
+
+# 3. Probe account health and preview which account would serve next
+codex-multi-auth check
+codex-multi-auth forecast --live
+```
+
+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).
+
+Run Codex through the wrapper so requests rotate across the pool:
+
+```bash
+codex-multi-auth-codex          # interactive TUI, rotation on by default
+codex-multi-auth-codex exec "summarize this repo"
+mcodex                          # same wrapper, shorter name
+```
+
+## Command map
+
+`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).
+
+| Group | Commands | Purpose |
+| --- | --- | --- |
+| Accounts | `login`, `list`, `status`, `switch <i>`, `unpin`, `workspace` | sign in, inspect the pool, pin or switch the active account, pick workspaces |
+| Selection | `forecast`, `best`, `why-selected`, `check`, `limits`, `models` | preview, explain, and probe which account serves the next request |
+| Runtime | `rotation status` `enable` `disable` `bind-app` `unbind-app` `reset-runtime` `reset-rate-limits` | inspect and control live rotation and the app bind |
+| Repair | `fix`, `doctor`, `verify`, `verify-flagged`, `uninstall` | diagnose and repair storage, flagged accounts, and install residue |
+| Governance | `usage`, `budget`, `account`, `monitor`, `history`, `resets` | usage ledger, budget limits, tags/weights/pause/drain, snapshots |
+| Local clients | `bridge`, `integrations` | bearer tokens and client snippets for the loopback bridge |
+| Config | `config explain` `template`, `init-config`, `debug bundle`, `features` | effective-config report, config templates, sanitized debug bundle |
+
+Everyday examples:
+
+```bash
+codex-multi-auth switch 2                     # pin account #2
+codex-multi-auth report --live --json         # full machine-readable health report
+codex-multi-auth fix --live --model gpt-5.5   # live repair probes with a chosen model
+codex-multi-auth doctor --fix                 # diagnose and apply the safest fixes
+codex-multi-auth usage --since 24h --by model # local usage ledger summary
+codex-multi-auth rotation status              # is live rotation enabled?
+```
+
+## Runtime rotation, in one paragraph
+
+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 and model-discovery calls, and never writes account emails or tokens to client headers or logs. 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`.
+
+## Where state lives
+
+| What | Path |
+| --- | --- |
+| Accounts, settings, quota cache, usage ledger, policies, observability | `~/.codex/multi-auth/` |
+| Per-project account pools | `~/.codex/multi-auth/projects/<project-key>/` |
+| Official Codex state (kept by the official install) | `~/.codex/` |
+| Override the multi-auth root | `CODEX_MULTI_AUTH_DIR=<path>` |
+
+Full path map: [docs/reference/storage-paths.md](docs/reference/storage-paths.md).
+
+## Troubleshooting in 60 seconds
+
+```bash
+codex-multi-auth doctor --fix
+codex-multi-auth check
+codex-multi-auth forecast --live
+```
+
+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).
+
+## Documentation
+
+| Doc | What it covers |
+| --- | --- |
+| [docs/index.md](docs/index.md) | Product overview — what it does at runtime and who needs it |
+| [docs/README.md](docs/README.md) | Full documentation portal and sitemap |
+| [docs/getting-started.md](docs/getting-started.md) | Install, first login, day-1 commands |
+| [docs/features.md](docs/features.md) | Feature tour |
+| [docs/architecture.md](docs/architecture.md) | Components, request flow, trust boundaries |
+| [docs/configuration.md](docs/configuration.md) | Settings and environment overrides |
+| [docs/reference/commands.md](docs/reference/commands.md) | Every command, flag, and hotkey |
+| [docs/reference/public-api.md](docs/reference/public-api.md) | Public API stability tiers and semver contract |
+| [docs/troubleshooting.md](docs/troubleshooting.md) | Recovery playbooks |
+| [docs/faq.md](docs/faq.md) | Common questions |
+| [docs/upgrade.md](docs/upgrade.md) | Version and legacy-package migration |
+| [docs/privacy.md](docs/privacy.md) | Data handling and local storage behavior |
+
+## Release notes
+
+- Current stable: [v2.17.3](docs/releases/v2.17.3.md) — `npm i -g codex-multi-auth`
+- Earlier stable lines: [v2.6.0](docs/releases/v2.6.0.md), [v2.5.0](docs/releases/v2.5.0.md)
+- Full release archive: [docs/README.md#release-history](docs/README.md#release-history)
+
+## Terms and license
+
+`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.
+
+MIT license — see [LICENSE](LICENSE).