Skip to content

ndycode/codex-multi-auth

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

897 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

codex-multi-auth

npm version npm downloads

Codex CLI-first multi-account OAuth manager for the official @openai/codex CLI.

2026-02-28 12_54_58-prompt txt ‎- Notepads

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
  • Experimental settings tab for staged sync, backup, and refresh-guard controls
  • 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

Terms and Usage Notice

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

Installation

For Humans

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 wrapper package version.

codex --version
codex-multi-auth --version
codex auth status
For LLM Agents

Step-by-step

  1. Install global package:
    • npm i -g codex-multi-auth
  2. Run first login flow with codex auth login
  3. Validate state with codex auth status and codex auth check
  4. Confirm routing with codex auth forecast --live

Verification

codex auth status
codex auth check

Quick Start

Install and sign in:

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

Verify the wrapper and the new account:

codex auth status
codex auth check

Use these next:

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

If browser launch is blocked, use the alternate login paths in docs/getting-started.md.


Command Toolkit

Start here

Command What it answers
codex auth login How do I add or re-open the account menu?
codex auth status Is the wrapper active right now?
codex auth check Do my saved accounts look healthy?

Daily use

Command What it answers
codex auth list Which accounts are saved and which one is active?
codex auth switch <index> How do I move to a different saved account?
codex auth forecast --live Which account looks best for the next session?

Repair

Command What it answers
codex auth verify-flagged Can any previously flagged account be restored?
codex auth fix --dry-run What safe storage or account repairs are available?
codex auth doctor --fix Can the CLI diagnose and apply the safest fixes now?

Advanced

Command What it answers
codex auth report --live --json How do I get the full machine-readable health report?
codex auth fix --live --model gpt-5-codex How do I run live repair probes with a chosen model?

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
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 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
`CODEX_TUI_GLYPHS=ascii unicode
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:

codex auth status
codex auth check
codex 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 for rollout guidance.


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

These flows are intentionally non-destructive by default: sync previews before apply, destination-only accounts are preserved, and backup filename collisions fail safely.


Troubleshooting

60-second recovery
codex auth doctor --fix
codex auth check
codex auth forecast --live

If still broken:

codex auth login
Common symptoms
  • codex auth unrecognized: run where codex, then follow docs/troubleshooting.md for routing fallback commands
  • 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
  • Browser launch is blocked or you are in a headless shell: re-run codex auth login --manual or set CODEX_AUTH_NO_BROWSER=1
  • missing field id_token / token_expired / refresh_token_reused: re-login affected account
Diagnostics pack
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

Documentation


Release Notes

License

MIT License. See LICENSE.

Legal
  • Not affiliated with OpenAI.
  • "ChatGPT", "Codex", and "OpenAI" are trademarks of OpenAI.
  • You assume responsibility for your own usage and compliance.