codex-multi-auth 0.1.0 → 0.1.1

package/README.md

@@ -1,162 +1,286 @@
 # 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)
+[![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)
 
-Codex CLI-first multi-account OAuth manager for the official Codex CLI.
+Codex CLI-first multi-account OAuth manager for the official `@openai/codex` CLI.
 
-* * *
+<img width="1270" height="729" alt="2026-02-28 12_54_58-prompt txt ‎- Notepads" src="https://github.com/user-attachments/assets/0cecb77e-a6d3-432a-ba48-3577db0c7093" />
 
-## Quick Start
 
-Install from source (current project workflow):
+> [!NOTE]
+> Legacy scoped prerelease package `@ndycode/codex-multi-auth` is migration-only.
+> Use `codex-multi-auth` for all new installs.
+## What You Get
+
+- Canonical `codex auth ...` workflow for account login, switching, checks, and diagnostics
+- Multi-account OAuth pool with health-aware selection and automatic failover
+- Project-scoped account storage under `~/.codex/multi-auth/projects/<project-key>/...`
+- Interactive dashboard for account actions and settings
+- Forecast, report, fix, and doctor commands for operational safety
+- Flagged account verification and restore flow
+- Session affinity and live account sync controls
+- Proactive refresh and preemptive quota deferral controls
+- Codex-oriented request/prompt compatibility with strict runtime handling
+- Stable docs set for install, config, troubleshooting, and upgrade paths
+
+---
+
+<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 plugin, 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 install -g @openai/codex
-git clone https://github.com/ndycode/codex-multi-auth.git
-cd codex-multi-auth
-npm install
-npm run build
-npm link
+npm i -g @openai/codex
+npm i -g codex-multi-auth
 ```
 
-Add and verify accounts:
+### Option B: Migrate from legacy scoped prerelease
 
 ```bash
-codex auth login
+npm uninstall -g @ndycode/codex-multi-auth
+npm i -g codex-multi-auth
+```
+
+### Option C: Verify wiring
+
+```bash
+codex --version
+codex auth status
+```
+
+</details>
+
+<details>
+<summary><b>For LLM Agents</b></summary>
+
+### Step-by-step
+
+1. Install global packages:
+   - `npm i -g @openai/codex`
+   - `npm i -g codex-multi-auth`
+2. Run first login flow with `codex auth login`
+3. Validate state with `codex auth list` and `codex auth check`
+4. Confirm routing with `codex auth forecast --live`
+
+### Verification
+
+```bash
+codex auth status
 codex auth list
 codex auth check
 ```
 
-If browser opens during `codex auth login`, that is expected. Complete OAuth and return to the same terminal.
+</details>
 
-* * *
+---
 
-## What You Get
+## Quick Start
 
-- `codex auth ...` commands for multi-account management.
-- Interactive beginner-friendly dashboard with hotkeys.
-- Health checks, forecasting, safe auto-fix, and diagnostics.
-- Live account sync and Codex CLI active-account state sync.
+```bash
+codex auth login
+codex auth list
+codex auth check
+codex auth forecast --live
+```
 
-* * *
+Day-1 command set:
 
-## Most-Used Commands
+```bash
+codex auth switch 2
+codex auth report --live --json
+codex auth fix --dry-run
+codex auth doctor --fix
+```
 
-| Command | Use it for |
-| --- | --- |
-| `codex auth login` | Add/manage accounts in the dashboard |
-| `codex auth list` | See saved accounts and current account |
-| `codex auth switch <index>` | Switch current account |
-| `codex auth check` | Quick health + live session checks |
-| `codex auth forecast --live` | Choose the best next account |
-| `codex auth fix --dry-run` | Preview safe fixes |
-| `codex auth fix` | Apply safe fixes |
-| `codex auth doctor --fix` | Diagnose and auto-repair common issues |
-| `codex auth report --live --json` | Full machine-readable report |
-| `codex auth features` | Print all implemented feature areas |
+---
 
-Complete command reference: [docs/reference/commands.md](docs/reference/commands.md)
+## Command Toolkit
 
-* * *
+| Command | What it does |
+| --- | --- |
+| `codex auth login` | Open interactive account dashboard |
+| `codex auth list` | List saved accounts and active account |
+| `codex auth status` | Print short runtime/status summary |
+| `codex auth switch <index>` | Set active account by index |
+| `codex auth check` | Run quick account health checks |
+| `codex auth verify-flagged` | Re-test flagged accounts and optionally restore |
+| `codex auth forecast --live` | Forecast best next account with live probes |
+| `codex auth report --live --json` | Generate machine-readable health report |
+| `codex auth fix --dry-run` | Preview safe repairs |
+| `codex auth fix --live --model gpt-5-codex` | Run repairs with live probe model |
+| `codex auth doctor --fix` | Diagnose and apply safe fixes |
+
+Compatibility aliases are also supported:
+- `codex multi auth ...`
+- `codex multi-auth ...`
+- `codex multiauth ...`
+
+---
 
 ## Dashboard Hotkeys
 
-Main dashboard:
+### Main dashboard
 
-- `Up` / `Down`: move
-- `Enter`: select
-- `1-9`: quick switch account
-- `/`: search
-- `?` or `H`: help
-- `Q`: back
+| Key | Action |
+| --- | --- |
+| `Up` / `Down` | Move selection |
+| `Enter` | Select/open |
+| `1-9` | Quick switch |
+| `/` | Search |
+| `?` | Toggle help |
+| `Q` | Back/cancel |
 
-Account detail menu:
+### Account details
 
-- `S`: set current
-- `R`: refresh login
-- `E`: enable/disable
-- `D`: delete account
+| Key | Action |
+| --- | --- |
+| `S` | Set current account |
+| `R` | Refresh/re-login account |
+| `E` | Enable/disable account |
+| `D` | Delete account |
 
-* * *
+---
 
-## Settings and Advanced Backend
+## Storage Paths
 
-Open:
+| 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` |
+| Logs | `~/.codex/multi-auth/logs/codex-plugin/` |
+| Per-project accounts | `~/.codex/multi-auth/projects/<project-key>/openai-codex-accounts.json` |
 
-```bash
-codex auth login
-# Settings
-```
+Override root with `CODEX_MULTI_AUTH_DIR=<path>`.
+
+---
 
-Settings are persisted in:
+## Configuration
 
+Primary config root:
 - `~/.codex/multi-auth/settings.json`
 - or `CODEX_MULTI_AUTH_DIR/settings.json` when custom root is set
 
-Reference:
-
-- [docs/reference/settings.md](docs/reference/settings.md)
+Selected runtime/environment overrides:
 
-* * *
-
-## Documentation Map
+| 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_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_FETCH_TIMEOUT_MS=<ms>` | Request timeout override |
+| `CODEX_AUTH_STREAM_STALL_TIMEOUT_MS=<ms>` | Stream stall timeout override |
 
-Start here:
+Validate config after changes:
 
-- Docs portal: [docs/README.md](docs/README.md)
-- Beginner setup: [docs/getting-started.md](docs/getting-started.md)
-- Full feature matrix: [docs/features.md](docs/features.md)
-- Configuration: [docs/configuration.md](docs/configuration.md)
-- Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)
-- Storage/path reference: [docs/reference/storage-paths.md](docs/reference/storage-paths.md)
-- Upgrade guide: [docs/upgrade.md](docs/upgrade.md)
-- Privacy/data handling: [docs/privacy.md](docs/privacy.md)
-
-Maintainer docs:
+```bash
+codex auth status
+codex auth check
+codex auth forecast --live
+```
 
-- Architecture: [docs/development/ARCHITECTURE.md](docs/development/ARCHITECTURE.md)
-- Config fields: [docs/development/CONFIG_FIELDS.md](docs/development/CONFIG_FIELDS.md)
-- Config flow: [docs/development/CONFIG_FLOW.md](docs/development/CONFIG_FLOW.md)
-- Testing: [docs/development/TESTING.md](docs/development/TESTING.md)
-- TUI parity checklist: [docs/development/TUI_PARITY_CHECKLIST.md](docs/development/TUI_PARITY_CHECKLIST.md)
+---
 
-* * *
+## Troubleshooting
 
-## Quick Troubleshooting
+<details open>
+<summary><b>60-second recovery</b></summary>
 
 ```bash
 codex auth doctor --fix
-codex auth list
+codex auth check
 codex auth forecast --live
 ```
 
-If command routing is broken:
+If still broken:
 
 ```bash
-where codex
-codex --version
-codex auth status
-codex multi auth status
+codex auth login
 ```
 
-* * *
+</details>
+
+<details>
+<summary><b>Common symptoms</b></summary>
+
+- `codex auth` unrecognized: run `where codex`, then try `codex multi auth status`
+- Switch succeeds but wrong account appears active: run `codex auth switch <index>`, then restart session
+- OAuth callback on port `1455` fails: free the port and re-run `codex auth login`
+- `missing field id_token` / `token_expired` / `refresh_token_reused`: re-login affected account
+
+</details>
 
-## Development
+<details>
+<summary><b>Diagnostics pack</b></summary>
 
 ```bash
-npm run typecheck
-npm run lint
-npm test
-npm run build
+codex auth list
+codex auth status
+codex auth check
+codex auth verify-flagged --json
+codex auth forecast --live
+codex auth fix --dry-run
+codex auth report --live --json
+codex 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)
+- 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/v0.1.1.md](docs/releases/v0.1.1.md)
+- Previous stable: [docs/releases/v0.1.0.md](docs/releases/v0.1.0.md)
+- Archived prerelease: [docs/releases/v0.1.0-beta.0.md](docs/releases/v0.1.0-beta.0.md)
+
+## License
 
-## Security and Usage Notice
+MIT License. See [LICENSE](LICENSE).
 
-This project is for personal development workflows. You are responsible for compliance with OpenAI policies.
+<details>
+<summary><b>Legal</b></summary>
 
-- Security policy: [SECURITY.md](SECURITY.md)
-- License: [LICENSE](LICENSE)
+- Not affiliated with OpenAI.
+- "ChatGPT", "Codex", and "OpenAI" are trademarks of OpenAI.
+- You assume responsibility for your own usage and compliance.
 
+</details>

package/assets/readme-hero.svg

@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="300" viewBox="0 0 1200 300" role="img" aria-label="OpenCode Codex OAuth">
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="300" viewBox="0 0 1200 300" role="img" aria-label="Codex Multi-Auth OAuth">
   <defs>
     <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
       <stop offset="0%" stop-color="#0f172a" />
@@ -20,7 +20,7 @@
     <path d="M205 80 L235 220" />
   </g>
   <text x="420" y="120" fill="#e2e8f0" font-size="42" font-family="'IBM Plex Sans','Segoe UI',Arial,sans-serif" font-weight="600">
-    OpenCode Codex OAuth
+    Codex Multi-Auth OAuth
   </text>
   <text x="420" y="170" fill="#cbd5f5" font-size="24" font-family="'IBM Plex Sans','Segoe UI',Arial,sans-serif">
     ChatGPT Plus/Pro auth for GPT-5.2 and Codex models

package/config/README.md

@@ -1,87 +1,30 @@
-# Configuration
-
-This directory contains the official OpenCode config templates for the ChatGPT Codex OAuth plugin.
-
-## Required: choose the right config file
-
-| File | OpenCode version | Description |
-|------|------------------|-------------|
-| [`opencode-modern.json`](./opencode-modern.json) | **v1.0.210+** | Variant-based config: 6 base models with 27 total presets |
-| [`opencode-legacy.json`](./opencode-legacy.json) | **v1.0.209 and below** | Legacy explicit entries: 22 individual model definitions |
-
-## Quick pick
-
-If your OpenCode version is v1.0.210 or newer:
-
-```bash
-cp config/opencode-modern.json ~/.config/opencode/opencode.json
-```
-
-If your OpenCode version is v1.0.209 or older:
-
-```bash
-cp config/opencode-legacy.json ~/.config/opencode/opencode.json
-```
-
-Check your version with:
-
-```bash
-opencode --version
-```
-
-## Why there are two templates
-
-OpenCode v1.0.210+ added model `variants`, so one model entry can expose multiple reasoning levels. That keeps modern config much smaller while preserving the same effective presets.
-
-Both templates include:
-- GPT-5.2, GPT-5 Codex, GPT-5.1, GPT-5.1 Codex, GPT-5.1 Codex Max, GPT-5.1 Codex Mini
-- Reasoning variants per model family
-- `store: false` and `include: ["reasoning.encrypted_content"]`
-- Context metadata (272k context / 128k output)
-
-## Spark model note
-
-The templates intentionally do **not** include `gpt-5.3-codex-spark` by default. Spark is often entitlement-gated at the account/workspace level, so shipping it by default causes avoidable startup failures for many users.
-
-If your workspace is entitled, you can add Spark model IDs manually.
-
-## Usage examples
-
-Modern template (v1.0.210+):
-
-```bash
-opencode run "task" --model=openai/gpt-5.2 --variant=medium
-opencode run "task" --model=openai/gpt-5-codex --variant=high
-```
-
-Legacy template (v1.0.209 and below):
-
-```bash
-opencode run "task" --model=openai/gpt-5.2-medium
-opencode run "task" --model=openai/gpt-5-codex-high
-```
-
-## Minimal config (advanced)
-
-A barebones debug template is available at [`minimal-opencode.json`](./minimal-opencode.json). It omits the full preset catalog.
-
-## Unsupported-model behavior
-
-Current defaults are strict entitlement handling:
-- `unsupportedCodexPolicy: "strict"` returns entitlement errors directly
-- set `unsupportedCodexPolicy: "fallback"` (or `CODEX_AUTH_UNSUPPORTED_MODEL_POLICY=fallback`) to enable automatic fallback retries
-- `fallbackToGpt52OnUnsupportedGpt53: true` keeps the legacy `gpt-5.3-codex -> gpt-5.2-codex` edge inside fallback mode
-- `unsupportedCodexFallbackChain` lets you override fallback order per model
-- Spark entitlement failures (`gpt-5.3-codex-spark`) force fallback immediately, even with strict policy, to support non-entitled workspaces
-
-Default fallback chain (when policy is `fallback`):
-- `gpt-5.3-codex -> gpt-5-codex -> gpt-5.2-codex`
-- `gpt-5.3-codex-spark -> gpt-5-codex -> gpt-5.3-codex -> gpt-5.2-codex` (only relevant if Spark IDs are added manually)
-- `gpt-5.2-codex -> gpt-5-codex`
-- `gpt-5.1-codex -> gpt-5-codex`
-
-## Additional docs
-
-- Main config reference: [`docs/configuration.md`](../docs/configuration.md)
-- Getting started: [`docs/getting-started.md`](../docs/getting-started.md)
-- Troubleshooting: [`docs/troubleshooting.md`](../docs/troubleshooting.md)
+# Config Templates
+
+These files are example model/provider templates for `codex-multi-auth`.
+
+## Primary (Codex-named)
+
+| File | Purpose |
+| --- | --- |
+| [`codex-modern.json`](./codex-modern.json) | Modern variant-based template |
+| [`codex-legacy.json`](./codex-legacy.json) | Legacy explicit-model template |
+| [`minimal-codex.json`](./minimal-codex.json) | Minimal debug template |
+
+## Notes
+
+- These templates are optional for the OAuth account manager flow.
+- Core auth commands use `codex auth login`.
+
+## Defaults Included
+
+- GPT-5.x Codex model families
+- `store: false`
+- `include: ["reasoning.encrypted_content"]`
+- Sensible fallback behavior for unsupported model entitlements
+
+## Related Docs
+
+- [`../docs/configuration.md`](../docs/configuration.md)
+- [`../docs/getting-started.md`](../docs/getting-started.md)
+- [`../docs/reference/settings.md`](../docs/reference/settings.md)
+