codex-multi-auth: Instructions file for Codex

PROJECT KNOWLEDGE BASE

Generated: 2026-10-11 Commit: 40c1e2e7 Branch: main Package version: 2.24.0

OVERVIEW

codex-multi-auth is a Codex CLI-first OAuth account manager and optional forwarding wrapper for the official Codex CLI. The architecture is manager-first: the codex-multi-auth bin (scripts/codex-multi-auth.js) owns the account-management CLI — 31 subcommands dispatched through lib/codex-manager.ts (runCodexMultiAuthCli), codex-multi-auth login ≡ codex-multi-auth auth login. The codex-multi-auth-codex bin (scripts/codex.js) owns explicit wrapper forwarding to the official Codex CLI plus shadow CODEX_HOME and runtime-rotation-proxy setup; mcodex is a launcher-only convenience wrapper over scripts/codex.js; codex-multi-auth-app-launcher is a reversible OS launcher routing helper. Runtime rotation is default-on: forwarded Responses/model traffic routes through a loopback-only account-rotation proxy (provider id codex-multi-auth-runtime-proxy). Local governance (usage ledger, budget guards, account policies, routing profiles, quota cache, local bridge tokens) stays file-backed under the multi-auth root. index.ts remains the exported plugin-host compatibility entry, but the primary product surface is the account manager, optional wrapper, storage, runtime proxy, governance commands, and repair tooling.

STRUCTURE

./
├── scripts/
│   ├── codex-multi-auth.js    # `codex-multi-auth` bin: standalone account-manager CLI entrypoint
│   ├── codex.js               # `codex-multi-auth-codex` bin: official-CLI forwarder, shadow CODEX_HOME + runtime proxy setup
│   ├── mcodex.js              # `mcodex` bin: launcher only — forwards to codex.js; optional --monitor / --tmux
│   ├── codex-app-launcher.js  # `codex-multi-auth-app-launcher` bin: reversible Windows/macOS/Linux launcher routing
│   ├── codex-routing.js       # auth-subcommand routing + compatibility alias normalization
│   ├── codex-bin-resolver.js  # official Codex binary discovery (env override → npm → prefix roots → PATH)
│   ├── codex-app-router.js    # detached persistent localhost router behind `rotation bind-app` (shipped, not a bin)
│   ├── postinstall.js         # notice-only npm hook; real setup is lib/runtime/first-run.ts
│   ├── preuninstall.js        # shipped but not an npm hook; `uninstall` subcommand replicates it
│   ├── install-codex-auth-utils.js  # installer helpers (install-codex-auth.js is repo-only, not shipped)
│   ├── repo-hygiene.js        # `clean`/`check` repo hygiene + Windows retry helpers
│   ├── copy-oauth-success.js, generate-config-schema.mjs  # build tooling
│   ├── check-pack-budget.mjs + -lib.js                    # package size budget check
│   ├── test-model-matrix.js, benchmark-*.mjs, bench-format/, test-all-models.sh, validate-model-map.sh  # matrix/bench tooling
│   └── audit-dev-allowlist.js, update-vendor-provenance.mjs, verify-vendor-provenance.mjs  # audit/vendor tooling
├── index.ts                  # plugin-host compatibility entry (`.` export: OpenAIOAuthPlugin)
├── lib/                      # core runtime logic (see lib/AGENTS.md)
│   ├── auth/                 # OAuth flow, PKCE, dual-bind callback server, device auth, token utils
│   ├── storage.ts + storage/ # V3 account pool: load/save, three-way snapshot merge, dedup, backups/WAL, flagged pool, file/json-store locks
│   ├── accounts.ts + accounts/ # pool facade, health scoring, cooldowns, per-account rate limits
│   ├── runtime-rotation-proxy.ts + runtime/ # loopback Responses/model proxy; app bind, first-run, native binding, selection, quota, checks
│   ├── request/              # request transform, headers, SSE handling, failover/backoff policy
│   ├── policy/               # runtime policy composition + hot-path store caches
│   ├── usage/                # append-only local usage ledger, pricing, redaction
│   ├── codex-cli/            # official Codex CLI state sync + writer helpers
│   ├── codex-manager.ts + codex-manager/ # CLI dispatcher, command modules, settings hub, login menus
│   ├── prompts/              # model-family prompts, GitHub ETag cache
│   ├── context-budget*/ + context-overflow.ts  # proactive budget guard + reactive overflow → synthesized replies
│   ├── oc-chatgpt-*.ts       # oc-chatgpt multi-auth interop (target detect, import adapter, sync orchestrator)
│   ├── recovery/             # conversation recovery state
│   ├── tools/                # hashline helper tools
│   ├── ui/                   # TUI rendering, menus, copy, theme, select
│   └── (flat modules)        # governance stores, quota, refresh machinery, rotation, config, schemas, utils
├── test/                     # vitest suites (see test/AGENTS.md) — 424 files incl. property/ + chaos/
├── docs/                     # user docs + reference/, releases/ (~87), development/ runbooks, audits/, design/, benchmarks/
├── config/                   # pluginConfig templates (modern/legacy/minimal) + generated JSON schema
├── vendor/                   # vendored codex-ai-plugin + codex-ai-sdk type-only shims (+ provenance.json)
├── assets/                   # static assets (icons, hero image)
├── bench/                    # format benchmark harness
├── skills/                   # codex-auth-setup skill (referenced by plugin manifest; not in files[])
├── .github/                  # CI workflows, issue/PR templates, plugin scanner fixtures
└── dist/                     # build output (generated, do not edit)