Imported from dkraemerwork/opencode-openai-multi-auth (AGENTS.md). Install upstream with npx skills add dkraemerwork/opencode-openai-multi-auth. Copyright stays with the author.

AGENTS.md

This file provides coding guidance for AI agents (including Claude Code, Codex, and others) when working with code in this repository.

Overview

This is an opencode plugin that enables OAuth authentication with OpenAI's ChatGPT Plus/Pro Codex backend. It allows users to access gpt-5.2-codex, gpt-5.1-codex, gpt-5.1-codex-max, gpt-5.1-codex-mini, gpt-5.2, and gpt-5.1 models through their ChatGPT subscription instead of using OpenAI Platform API credits. Legacy GPT-5.0 models are automatically normalized to their GPT-5.1 equivalents.

Key architecture principle: 7-step fetch flow that intercepts opencode's OpenAI SDK requests, transforms them for the ChatGPT backend API, and handles OAuth token management.

Build & Test Commands

# Build (compiles TypeScript + copies HTML file)
npm run build

# Type checking only (no build)
npm run typecheck

# Run all tests
npm test

# Watch mode for TDD
npm run test:watch

# Interactive test UI
npm run test:ui

# Coverage report
npm run test:coverage

Important: The build script has a critical step that copies lib/oauth-success.html to dist/lib/. This HTML file is required for the OAuth callback flow.

Code Architecture

Plugin Flow (index.ts)

The main entry point orchestrates a 7-step fetch flow:

1. Token Management: Check token expiration, refresh if needed
2. URL Rewriting: Transform OpenAI Platform API URLs → ChatGPT backend API (https://chatgpt.com/backend-api/codex/responses)
3. Request Transformation:
   • Normalize model names (all variants → gpt-5.2, gpt-5.2-codex, gpt-5.1, gpt-5.1-codex, gpt-5.1-codex-max, gpt-5.1-codex-mini, gpt-5, gpt-5-codex, or codex-mini-latest)
   • Inject Codex system instructions from latest GitHub release
   • Apply reasoning configuration (effort, summary, verbosity)
   • Add CODEX_MODE bridge prompt (default) or tool remap message (legacy)
   • Filter OpenCode system prompts when in CODEX_MODE
   • Filter conversation history (remove rs_* IDs for stateless operation)
4. Headers: Add OAuth token + ChatGPT account ID
5. Request Execution: Send to Codex backend
6. Response Logging: Optional debug logging (ENABLE_PLUGIN_REQUEST_LOGGING=1)
7. Response Handling: Convert SSE to JSON (non-tool requests) or pass through

Module Organization

Core Plugin (index.ts)

• Plugin definition and main fetch orchestration
• Multi-account coordination via AccountManager
• Toast notifications for account switches/rate limits
• Configuration loading and CODEX_MODE determination

Account Management (lib/accounts/)

• manager.ts: AccountManager class - handles multi-account rotation, rate limit tracking, token refresh
• types.ts: ManagedAccount, AccountsStorage, MultiAccountConfig interfaces
• index.ts: Module exports

Authentication (lib/auth/)

• auth.ts: OAuth flow (PKCE, token exchange, JWT decoding, refresh)
• server.ts: Local HTTP server for OAuth callback (port 1455)
• browser.ts: Platform-specific browser opening

Request Handling (lib/request/)

• fetch-helpers.ts: 10 focused helper functions for main fetch flow
• request-transformer.ts: Body transformations (model normalization, reasoning config, input filtering)
• response-handler.ts: SSE to JSON conversion

Prompts (lib/prompts/)

• codex.ts: Fetches Codex instructions from GitHub (ETag-cached), tool remap message
• codex-opencode-bridge.ts: CODEX_MODE bridge prompt for CLI parity

Configuration (lib/)

• config.ts: Plugin config loading, CODEX_MODE determination
• constants.ts: All magic values, URLs, error messages
• types.ts: TypeScript type definitions
• logger.ts: Debug logging (controlled by env var)

Key Design Patterns

1. Stateless Operation: Uses store: false + include: ["reasoning.encrypted_content"]

• Allows multi-turn conversations without server-side storage
• Encrypted reasoning content persists context across turns

2. CODEX_MODE (enabled by default):

• Priority: CODEX_MODE env var > ~/.opencode/openai-codex-auth-config.json > default (true)
• When enabled: Filters out OpenCode system prompts, adds Codex-OpenCode bridge prompt with Task tool & MCP awareness
• When disabled: Uses legacy tool remap message
• Bridge prompt (~550 tokens): Tool mappings, available tools, working style, Task tool/sub-agent awareness, MCP tool awareness
• Prompt verification: Caches OpenCode's codex.txt from GitHub (ETag-based) to verify exact prompt removal, with fallback to text signature matching

3. Configuration Merging:

• Global options (provider.openai.options) + per-model options (provider.openai.models[name].options)
• Model-specific options override global
• Plugin defaults: reasoningEffort: "medium", reasoningSummary: "auto", textVerbosity: "medium"

4. Model Normalization (GPT-5.0 → GPT-5.1 migration):

• All gpt-5.2-codex* variants → gpt-5.2-codex (newest Codex model, supports xhigh)
• All gpt-5.1-codex-max* variants → gpt-5.1-codex-max
• All gpt-5.1-codex* variants → gpt-5.1-codex
• All gpt-5.1-codex-mini* variants → gpt-5.1-codex-mini
• All gpt-5.2 variants → gpt-5.2
• All gpt-5.1 variants → gpt-5.1
• Legacy mappings (GPT-5.0 being phased out):
  • gpt-5-codex* variants → gpt-5.1-codex
  • gpt-5-codex-mini* or codex-mini-latest → gpt-5.1-codex-mini
  • gpt-5* variants (including gpt-5-mini, gpt-5-nano) → gpt-5.1
• minimal effort auto-normalized to low for Codex families (including GPT-5.2 Codex) and clamped to medium (or high when requested) for Codex Mini

5. Model-Specific Prompt Selection:

• Different prompts for different model families (matching Codex CLI):
  • gpt-5.2-codex* → gpt-5.2-codex_prompt.md (117 lines, Codex CLI agent prompt)
  • gpt-5.1-codex-max* → gpt-5.1-codex-max_prompt.md (117 lines, frontend design guidelines)
  • gpt-5.1-codex*, codex-* → gpt_5_codex_prompt.md (105 lines, coding focus)
  • gpt-5.2* → gpt_5_2_prompt.md (GPT‑5.2 general family)
  • gpt-5.1* → gpt_5_1_prompt.md (368 lines, full behavioral guidance)
• getModelFamily() determines prompt selection based on normalized model

6. Codex Instructions Caching:

• Fetches from latest release tag (not main branch)
• ETag-based HTTP conditional requests per model family
• Separate cache files per family: gpt-5.2-codex-instructions.md, codex-max-instructions.md, codex-instructions.md, gpt-5.2-instructions.md, gpt-5.1-instructions.md
• Cache invalidation when release tag changes
• Falls back to bundled version if GitHub unavailable

Development Patterns

Adding New Configuration Options

1. Add to ConfigOptions interface in lib/types.ts
2. Update transformRequestBody() in lib/request/request-transformer.ts
3. Add tests in test/request-transformer.test.ts
4. Document in README.md configuration section

Modifying Request Transformation

All request transformations go through transformRequestBody():

• Input filtering: filterInput(), filterOpenCodeSystemPrompts()
• Message injection: addCodexBridgeMessage() or addToolRemapMessage()
• Reasoning config: getReasoningConfig() (follows Codex CLI defaults, not opencode defaults)
• Model config: getModelConfig() (merges global + per-model options)

OAuth Flow Modifications

OAuth implementation follows OpenAI Codex CLI patterns:

• Client ID: app_EMoamEEZ73f0CkXaXp7hrann
• PKCE with S256 challenge
• Special params: codex_cli_simplified_flow=true, originator=codex_cli_rs
• Callback server on port 1455 (matches Codex CLI)

Testing Strategy

• 191 comprehensive tests covering all modules
• Test files mirror source structure (test/auth.test.ts ↔ lib/auth/auth.ts)
• Mock-heavy testing (no actual network calls or file I/O in tests)
• Focus on edge cases: token expiration, model normalization, input filtering, CODEX_MODE toggling

Important Configuration Differences

This plugin intentionally differs from opencode defaults because it accesses ChatGPT backend API (not OpenAI Platform API):

File Paths & Locations

• Plugin config: ~/.opencode/openai-codex-auth-config.json
• Accounts storage: ~/.config/opencode/openai-accounts.json
• Cache dir: ~/.opencode/cache/
  • codex-instructions.md (Codex CLI instructions from GitHub)
  • codex-instructions-meta.json (ETag + release tag for Codex instructions)
  • opencode-codex.txt (OpenCode system prompt from GitHub, for verification)
  • opencode-codex-meta.json (ETag for OpenCode prompt)
• Debug logs: ~/.opencode/logs/codex-plugin/ (when ENABLE_PLUGIN_REQUEST_LOGGING=1)
• OAuth callback: http://localhost:1455/auth/callback

Environment Variables

• CODEX_MODE: Override config file (1=enable, 0=disable)
• ENABLE_PLUGIN_REQUEST_LOGGING: Enable detailed request logging (1=enable)
• OPENCODE_OPENAI_QUIET: Disable toast notifications (1=enable)
• OPENCODE_OPENAI_DEBUG: Enable debug logging for multi-account (1=enable)
• OPENCODE_OPENAI_STRATEGY: Account selection strategy (sticky, round-robin, hybrid)
• OPENCODE_OPENAI_PID_OFFSET: Enable PID-based account offset (1=enable)

TypeScript Configuration

• Target: ES2022
• Module: ES2022 with bundler resolution
• Output: ./dist/
• Strict mode enabled
• Declaration files generated
• Source maps enabled
• Excludes: test/, node_modules/, dist/

Dependencies

Production:

• @openauthjs/openauth (OAuth PKCE implementation)

Development:

• @opencode-ai/plugin (peer dependency)
• vitest (testing framework)
• TypeScript

Zero external runtime dependencies - only uses Node.js built-ins for file I/O, HTTP, crypto.