relay-ai: Instructions file for Codex

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository. Note that the codebase supports Claude Code, OpenAI Codex, and Google Gemini CLI.

Docker / always-on gateway: If a user asks to run Relay AI in a container, follow docs/DOCKER.md (AI checklist + questions). That deploys Server + Admin UI only — not desktop app launch.

Commands

npm run build       # compile TypeScript → dist/cli.js (via tsup, ESM, shebang injected)
npm test            # run all tests with vitest
npm run typecheck   # type-check without emitting (tsc --noEmit)
npm run dev         # watch mode build

# Run a single test file
npx vitest run tests/env.test.ts
npx vitest run tests/models.test.ts

# Test the CLI locally (run npm link first if not linked)
relay-ai --help
relay-ai models          # manage favorite models for mid-session switching
relay-ai Codex --dry-run   # simulate full first-run without writing anything
relay-ai Codex --setup    # re-ask subscription tier
relay-ai Codex --trace    # write debug log to /tmp/relay-ai-debug.log and print errors on exit
relay-ai server           # foreground OpenCode/registry API gateway
relay-ai server --vertex  # foreground Vertex AI gateway (gcloud ADC)
relay-ai codex            # Codex CLI with registry providers (see docs/CODEX.md)
relay-ai codex-app        # Codex desktop app (macOS/Windows/Linux; see docs/CODEX.md)
relay-ai gemini           # Gemini CLI with registry providers (see docs/GEMINI.md)

# Rebuild after code changes before testing manually
npm run build && relay-ai --version

Architecture

Entry point: src/cli.ts orchestrates the full flow. Every other module is a focused unit with no side effects at import time.

Legacy Claude launch data flow (relay-ai claude):

cli.ts
  → findClaudeBinary()         [launch.ts — locate Codex binary]
  → fetchLocalProviders()      [providers.ts — ephemeral opencode serve, GET /config/providers, normalize]
  → p.select "Which provider?" [shown when local providers are available]

  ── OpenCode cloud path (default) ──
  → resolveOrCollectApiKey()   [reads env, OS credential store (all platforms), or prompts user]
  → askSubscriptionTier()      [prompts.ts — one-time question, saved to conf store]
  → getModels()                [models.ts — API fetch + cache enrichment + format classification]
  → runWizard()                [prompts.ts — backend/model selector, filters unsupported]

  ── Local provider path ──
  → pickLocalModel()           [prompts.ts — filter/select model from local provider]

  ── Shared launch (no favorites) ──
  → startProxy()               [proxy.ts — single-model wrapper around startProxyCatalog]
  → buildChildEnv(baseUrl, …)  [env.ts — removes 17 conflicting vars, sets OpenCode vars]
  → launchClaude()             [launch.ts — spawn with stdio:inherit]
  → proxyHandle.close()        [stops proxy after Codex exits]

  ── Switch-menu launch (favorites.length > 0) ──
  → buildCatalogRoutes()       [catalog.ts — starting model + favorites, max 50]
  → startProxyCatalog()        [proxy.ts — multi-route proxy, alias IDs per model]
  → buildChildEnv(…, gatewayDiscovery=true)  [sets CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1]
  → launchClaudeViaCatalog()   [cli.ts — shared launch + trace cleanup]