Imported from ndycode/oc-codex-multi-auth (AGENTS.md). Install upstream with npx skills add ndycode/oc-codex-multi-auth. Copyright stays with the author.

PROJECT KNOWLEDGE BASE

Branch: main Package version: see package.json (version field).

OVERVIEW

oc-codex-multi-auth is an OpenCode plugin for ChatGPT Plus/Pro OAuth, Codex/GPT-5/GPT-6 request routing (including GPT-6 Astra, Daybreak, and GPT-5.6 Sol/Terra/Luna responses-lite), multi-account rotation, account switching, health checks, quota status, diagnostics, and recovery tools. The npm bin is an installer that manages OpenCode provider/TUI config and also runs standalone CLI commands (doctor, status, list, limits, dashboard, health, diag, warm). OpenCode loads index.ts as the provider plugin and tui.ts as the prompt quota status plugin. Runtime account state stays local under ~/.opencode with per-project pools enabled by default.

STRUCTURE

./
├── index.ts              # OpenCode provider plugin entry: auth loader, fetch pipeline, tool registry context
├── tui.ts                # OpenCode TUI plugin: prompt quota status and quota details
├── lib/                  # core runtime logic (see lib/AGENTS.md)
├── test/                 # vitest suites (see test/AGENTS.md)
├── scripts/              # installer, standalone CLI, build, audit, and validation helpers
├── config/               # opencode.json examples (modern/full/legacy/minimal)
├── docs/                 # public docs, architecture, maintainer guides
├── skills/               # repo-local setup skill
├── assets/               # static assets
├── .codex-plugin/        # plugin metadata for Codex skill/plugin tooling
└── dist/                 # build output (generated, do not edit)

WHERE TO LOOK

CONVENTIONS

• Source: root index.ts, tui.ts, lib/, and scripts/; dist/ is generated output.
• ESLint flat config: no-explicit-any enforced, unused args prefixed _.
• ESM only ("type": "module"), Node >= 18.
• Canonical package/plugin name is oc-codex-multi-auth.
• The npm bin is an installer and thin standalone CLI, not a long-running runtime daemon.
• OpenCode loads the provider plugin and TUI plugin from built package exports.
• Default installer mode only registers plugin entries and preserves provider.openai; --modern writes compact config (13 bases / 59 variants), --full adds 59 explicit selector IDs, and --legacy writes legacy explicit-only config; --dry-run and --no-cache-clear are supported.
• Runtime requests preserve Codex stateless requirements: store: false and reasoning.encrypted_content.
• GPT-6 Astra, Daybreak and GPT-5.6 use responses-lite shaping and default client identity opencode; other models default to codex_cli_rs. All three are catalog-read (use_responses_lite: true). Astra's entry also ships an empty base_instructions, so it reads its prompt file rather than catalog text.
• Account selection uses rotationStrategy (hybrid default) with health scoring in lib/rotation.ts.
• Per-project account storage is enabled by default.
• Optional OS keychain backend is opt-in with CODEX_KEYCHAIN=1.

ANTI-PATTERNS (THIS PROJECT)

• Do not edit dist/ or tmp* directories.
• Do not use as any, @ts-ignore, or @ts-expect-error.
• Do not open public security issues; see SECURITY.md.
• Do not hardcode ports other than OAuth callback port 1455; use existing constants/helpers.
• Do not remove store: false or reasoning.encrypted_content from shipped config templates.
• Do not treat oc-chatgpt-multi-auth as current except in migration/cleanup logic.
• Do not expose account emails, access tokens, refresh tokens, or raw prompt/response bodies in normal diagnostics.
• Do not silently delete JSON credentials when keychain operations fail.
• Do not document boolean env overrides as truthy for "true" or "yes". Only "1" is truthy.

COMMANDS

npm run build            # clean dist + tsc + copy oauth-success.html
npm run typecheck        # type checking only
npm test                 # vitest once
npm run test:coverage    # vitest coverage
npm run audit:ci         # prod audit + dev allowlist
npm run test:watch       # vitest watch mode
npm run lint             # eslint

Standalone CLI examples:

npx -y oc-codex-multi-auth@latest
npx -y oc-codex-multi-auth@latest --full
oc-codex-multi-auth warm
oc-codex-multi-auth status --json
oc-codex-multi-auth doctor

NOTES

• OAuth redirect URI: http://localhost:1455/auth/callback (registered with the Codex OAuth client). The callback server binds both 127.0.0.1:1455 and [::1]:1455.
• ChatGPT backend requires store: false, include reasoning.encrypted_content.
• OpenCode config: ~/.config/opencode/opencode.json.
• OpenCode TUI config: ~/.config/opencode/tui.json.
• OpenCode auth tokens: ~/.opencode/auth/openai.json.
• Plugin config: ~/.opencode/openai-codex-auth-config.json.
• Per-project accounts: ~/.opencode/projects/<project-key>/oc-codex-multi-auth-accounts.json.
• Global accounts: ~/.opencode/oc-codex-multi-auth-accounts.json.
• Flagged accounts: oc-codex-multi-auth-flagged-accounts.json, written beside the active accounts file (per project when perProjectAccounts is on).
• Quota notification state: oc-codex-multi-auth-quota-notifications.json, written beside the active accounts file (per project when perProjectAccounts is on).
• Request logs: ~/.opencode/logs/codex-plugin/ when logging is enabled.
• Model catalog: 13 modern bases / 59 variants; legacy 59 explicit.
• Bases: gpt-6-astra, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5, gpt-5.5-fast, gpt-5.4-mini, gpt-5.4-nano, gpt-5.1-codex-max, gpt-5.1-codex, gpt-5.1-codex-mini, gpt-5.1, gpt-5-codex. Routed but deliberately unshipped (Daybreak-gated, add by hand): gpt-daybreak-blue-latest, gpt-daybreak-red-latest, gpt-5.6-cyber.
• Prompt templates sync from Codex CLI GitHub releases with ETag caching; 5.6 and Daybreak instructions come from the Codex model catalog. gpt-6-astra has a catalog entry, but its base_instructions is empty and the loader treats empty as absent, so Astra reads its prompt file until openai/codex publishes catalog text.
• 5xx server errors trigger account rotation and health penalty like network errors.
• API deprecation/sunset headers (RFC 8594) are logged as warnings.
• StorageError preserves original stack traces via cause parameter.
• saveToDiskDebounced errors are logged but do not crash the plugin.