Codex Integration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Codex Integration within the CCS (Claude Code Switch) project provides a robust bridge for managing, routing, and configuring the native Codex CLI alongside other providers like Claude and Factory Droid. It enables developers to switch between different Codex profiles, manage authentication states, and apply fine-grained configuration overrides (such as model reasoning effort and MCP server settings) through both a command-line interface and a web-based dashboard.
The integration scope includes a local dashboard service for diagnostics, an atomic configuration management system using TOML, and a quota-fetching mechanism that interacts with the ChatGPT backend API. By centralizing these controls, CCS allows users to run Codex sessions with transient overrides without manually editing the primary config.toml file.
Sources: README.md, src/web-server/services/codex-dashboard-service.ts:1-30, AGENTS.md
Core Architecture and Data Flow
The architecture is divided into a backend service layer that handles file I/O and diagnostics, a CLI layer for authentication and runtime execution, and a React-based frontend for visual management.
Configuration Management
CCS interacts with the Codex configuration primarily through the config.toml file, typically located in $CODEX_HOME. The CodexDashboardService provides methods to read, save, and patch this file using atomic writes to prevent data corruption.
The system ensures that changes to settings like model_reasoning_effort or mcp_servers are validated against known sets of allowed values before being committed to disk.
Sources: src/web-server/services/codex-dashboard-service.ts:182-210, src/web-server/services/codex-dashboard-service.ts:510-550
Diagnostic and Support Matrix
The integration includes a diagnostic engine that evaluates the state of the Codex binary and its configuration. It checks for binary installation, version compatibility, and whether the current build supports --config overrides, which is critical for CCS-backed routing.
| Diagnostic Category | Key Checks |
|---|---|
| Binary | Installation status, version, install directory, and --config override support. |
| Config | Active profile, model provider, feature flags, and project trust levels. |
| Warnings | Missing profiles, expired tokens, or insecure inline bearer tokens. |
| Support Matrix | Compatibility of specific flows (e.g., cliproxy, settings-with-bridge). |
Sources: src/web-server/services/codex-dashboard-service.ts:430-500, tests/unit/web-server/codex-dashboard-service.test.ts:145-180
Authentication and Profile Management
Codex authentication is managed through dedicated commands and a registry that tracks profiles. CCS supports importing legacy Codex authentication files (auth.json) into named profiles.
Import and Migration
The import-default command migrates legacy ~/.codex/auth.json files. It implements "Torn-Write Protection" by performing read-with-retry and validating the structural integrity of the JWT before migration. It also detects if a Codex process is already running to avoid race conditions during token refreshes.
Quota Tracking
The fetchCodexQuota function retrieves usage limits and reset times from the ChatGPT backend API. It extracts primary (5-hour) and secondary (weekly) windows for various metered features.
| Quota Data Field | Description |
|---|---|
usedPercent | The percentage of the quota consumed. |
remainingPercent | The remaining available quota. |
resetAfterSeconds | Seconds until the quota window resets. |
planType | Account plan level (e.g., Free, Plus, Pro, Team). |
Sources: src/cliproxy/quota/quota-fetcher-codex.ts:275-310, src/cliproxy/quota/quota-fetcher-codex.ts:600-650
Runtime and Overrides
CCS facilitates the execution of Codex with transient configuration overrides using the -c or --config flags.
Browser MCP Integration
A key feature is the ability to inject browser-based MCP (Model Context Protocol) tools into Codex sessions. Based on the project policy, CCS can automatically enable these tools or require manual activation via the --browser flag.
Config Normalization
CCS handles the normalization of Codex-specific "tuning aliases" (e.g., gpt-5.5-high-fast). When these models are requested, CCS decomposes the string into discrete configuration keys:
model:gpt-5.5model_reasoning_effort:highservice_tier:priority
Sources: tests/unit/targets/codex-runtime-integration.test.ts:540-570, ui/tests/unit/ui/lib/codex-effort.test.ts:10-35
Dashboard Implementation
The Codex Dashboard (implemented in ui/src/pages/codex.tsx) provides a dual-pane interface for configuration.
- Left Pane (Diagnostics & Tabs): Displays the Overview, Control Center, Docs, and Auth Profiles. It uses the
useCodexhook to fetch diagnostic data every 10 seconds. - Right Pane (Raw Editor): Provides a raw TOML editor for
config.tomlwith conflict detection (usingmtime) to prevent overwriting external changes.
Key UI components include:
CodexControlCenterTab: Structured inputs for top-level settings, project trust, and MCP servers.RawConfigEditorPanel: A Monaco-based editor for manual TOML editing.
Sources: ui/src/pages/codex.tsx:40-100, ui/src/hooks/use-codex.ts:70-90
Summary
Codex Integration in CCS serves as a sophisticated management layer for the native OpenAI Codex CLI. It bridges the gap between raw file-based configuration and modern, profile-driven workflows. By providing atomic configuration patching, robust authentication migration, and real-time quota monitoring, it ensures that developers can leverage Codex's capabilities with the same flexibility and safety as cloud-based providers.