Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt

Use this file to discover all available pages before exploring further.

​
Codex Provider

Access OpenAI Codex models through browser-based OAuth authentication. CCS defaults to the current Codex-recommended models and repairs known paid-only or preview-only defaults when the active account cannot use them.

​
Overview

The Codex provider enables Claude Code to use OpenAI’s Codex models through OAuth authentication - no API keys required. Simply authenticate once and CCS handles token management automatically. Provider Identifier: codex Command: ccs codex Supported Models:
  • GPT-5.4 - recommended default for most Codex tasks
  • GPT-5.4 Mini - fast, lower-cost option for lighter tasks and subagents
  • GPT-5.2 and GPT-5.3 Codex as older alternatives
  • GPT-5.3 Codex Spark in research preview for ChatGPT Pro subscribers
  • Interactive model picker via --config

​
Plan-Aware Defaults

Available since v7.54.0
CCS now checks the active Codex quota plan before startup when your settings reference a known paid-only or preview-only model.
  • If the active account is on the free Codex plan, CCS keeps your saved settings but sends runtime requests through gpt-5.4 or gpt-5.4-mini when the configured model is restricted
  • If CCS cannot verify the plan, it keeps your current model and prints a targeted warning with the safe fallback
  • The runtime fallback only touches known restricted Codex defaults (gpt-5.5, gpt-5.3-codex, and gpt-5.3-codex-spark); it does not rewrite unrelated provider settings

​
Authentication

​
First-Time Setup

# Run Codex for the first time
ccs codex "explain this code"

# Browser opens automatically
# → Complete OAuth login
# → Token cached at ~/.ccs/cliproxy/auth/
# → Future runs require no re-auth
Authentication Flow:
  1. Authorization Code flow via browser callback
  2. Callback server spawns on provider-specific port
  3. Token cached locally with auto-refresh
  4. Proactive token refresh prevents mid-request failures

​
Manual Authentication

# Authenticate without starting a session
ccs codex --auth

# Headless mode (server/SSH environments)
ccs codex --headless
# → Displays URL for manual browser authentication
# → Includes SSH tunnel instructions if needed

​
Logout

# Clear all Codex tokens
ccs codex --logout

​
Multi-Account Support

Manage multiple OpenAI accounts for different projects:

​
Add Account

# Add new account (preserves existing)
ccs codex --auth --add

​
List Accounts

# Show all authenticated Codex accounts
ccs codex --accounts

# Output:
# Accounts for codex:
#   [default] john (john@example.com)
#   sarah (sarah@company.com)

​
Switch Account

# Switch to specific account by nickname
ccs codex --use sarah

# Next command uses sarah's account
ccs codex "your prompt"

​
Rename Account

# Rename default account nickname
ccs codex --nickname work-account
Account Registry: ~/.ccs/cliproxy/accounts.json Auto-Nicknames: Generated from email prefix (e.g., john@gmail.com → john)

​
Real-Time Quota Display

CCS displays real-time quota information for Codex accounts via Dashboard and CLI.

​
Weekly Reset Schedule

Since v7.44.0, the dashboard exposes the weekly reset schedule for Codex accounts, showing exactly when your weekly quota resets.

​
Dashboard Display

Location: Dashboard → CLIProxy → Codex provider view Displays:
  • Core 5-hour usage window (e.g., “45/50 messages”)
  • Core weekly usage window (e.g., “210/500 messages”)
  • 5-hour limit reset time
  • Weekly limit reset time (with schedule)
  • Additional feature windows such as Codex Spark in tooltip/detail views when the upstream exposes them
Backend Caching:
  • Quota data cached for 2 minutes to reduce API load
  • Automatic re-authentication if token expired
  • Dashboard shows cached timestamp

​
CLI Quota Check

# View quota for all Codex accounts
ccs cliproxy quota --provider codex

# Output:
# Codex Quota (as of 2026-02-04 18:00:00):
#   john@example.com:
#     5-hour: 45/50 messages (resets in 6h)
#     Weekly: 210/500 messages (resets in 2d 6h)
Features:
  • Displays all authenticated Codex accounts
  • Shows cached timestamp (2-minute cache)
  • Indicates if re-authentication needed
  • Keeps preview or feature-specific windows separate from the core 5-hour and weekly summary so extra limits do not replace the main account view
Quota Response Caching: CCS caches quota responses to prevent excessive API calls:
Cache DurationApplies To
2 minutesQuota data (usage counts, reset times)
Token refreshAutomatic if expired during fetch
Cache Location: In-memory (not persisted to disk)

​
Model Information

Available Models:
Model IDNameMax EffortNotes
gpt-5.5GPT-5.5xhighNewest paid Codex model
gpt-5.4GPT-5.4xhighRecommended Codex default
gpt-5.4-miniGPT-5.4 MinihighDefault fast / haiku option
gpt-5.2GPT-5.2xhighOlder general-purpose model
gpt-5.3-codexGPT-5.3 CodexxhighOlder paid Codex model
gpt-5.3-codex-sparkGPT-5.3 Codex SparkxhighResearch preview, ChatGPT Pro
Model Suffixes: Append effort level directly: gpt-5.3-codex-medium, gpt-5.3-codex-high, gpt-5.3-codex-xhigh.

​
Reasoning Effort

CCS automatically injects OpenAI’s reasoning.effort parameter. The configured slot requests a default effort, then CCS caps it to the selected model’s supported maximum.

​
Effort Levels

LevelDescriptionToken Budget
mediumStandard reasoningBase level
highDeep reasoningModerate increase
xhighMaximum depthUp to 32K tokens

​
Automatic Effort Mapping

SourceRequested EffortEffective Behavior
Default / Opus slotxhighCapped by the selected model’s max supported level
Sonnet slothighUsed as-is unless the model only supports lower
Haiku slotmediumUsed as-is
--effort / model suffixExplicit valueUsed, then capped if the model cannot support it

​
How It Works

When you use Codex, CCS derives the effort from your configuration and then applies model-specific caps: 
# Default Codex model is gpt-5.4, so xhigh remains available
ccs codex "complex analysis task"

# Override effort explicitly
ccs codex --effort xhigh "deep analysis"
ccs codex --thinking xhigh "same as --effort (alias)"

# Model suffix pins effort
ccs codex  # model: gpt-5.3-codex-medium -> effort: medium

​
Cost Implications

Higher reasoning effort increases token consumption:
  • xhigh: Maximum tokens, deepest analysis
  • high: Moderate token increase
  • medium: Standard token usage
Reasoning effort is injected transparently. You don’t need to configure anything unless you want to override it. Unsupported higher efforts are capped to the model’s max level automatically.

​
Trace Logging

Enable verbose mode to see reasoning effort in request logs: 
ccs codex --verbose "your task"
# Output includes: reasoning.effort: xhigh

​
Runtime Targets

Available since v7.62.0
CCS can route the Codex provider to different CLI runtimes:

​
Native Codex Runtime

Use ccs-codex, ccsx, or ccsxp to run the Codex provider on the native Codex CLI: 
# Built-in aliases
ccs-codex "your prompt"
ccsx codex "implement auth flow"

# Codex-on-Codex power shortcut
ccsxp "your prompt"

# Explicit target flag
ccs codex --target codex "your prompt"
The Codex adapter uses transient -c overrides and CCS_CODEX_API_KEY env injection — it never rewrites ~/.codex/config.toml. ccsxp keeps Codex history in native ~/.codex by default, even if the parent shell has another CODEX_HOME set. Use CCSXP_CODEX_HOME only when you intentionally want separate ccsxp history.
See Codex Adapter for full details on supported profile types, alias configuration, and the dashboard control center.

​
Droid Runtime

Use Codex with the ccs-droid target for automated agent workflows: 
ccs-droid codex "run this task autonomously"
This routes the Codex provider through CCS’s Droid runtime for non-interactive automated execution.

​
Commands

​
Basic Usage

# Run with Codex
ccs codex "implement authentication flow"

# Interactive chat
ccs codex

# With reasoning effort
ccs codex --thinking xhigh "design this system"

​
Authentication Flags

FlagDescription
--authTrigger OAuth flow (no session)
--logoutClear all tokens
--headlessDisplay URL for remote auth
--auth --addAdd new account (keep existing)

​
Account Management Flags

FlagDescription
--accountsList all accounts
--use <nickname>Switch default account
--nickname <name>Rename default account

​
Storage Locations

PathPurpose
~/.ccs/cliproxy/auth/codex-*.jsonOAuth tokens (one per account)
~/.ccs/cliproxy/accounts.jsonAccount registry with nicknames
~/.ccs/codex.settings.jsonModel configuration
~/.ccs/cliproxy/config.yamlCLIProxy unified config

​
Requirements

  • OpenAI account with Codex OAuth access
  • Browser for OAuth (or --headless for servers)
  • Network access to OpenAI authentication servers

​
Token Management

Storage Format: 
{
  "type": "codex",
  "access_token": "...",
  "refresh_token": "...",
  "email": "user@example.com",
  "expired": "2024-12-31T23:59:59Z"
}
Auto-Refresh: Tokens refresh automatically 5 minutes before expiry Security: Tokens stored locally, never transmitted except to OpenAI

​
Troubleshooting

​
Browser Won’t Open

# Use headless mode
ccs codex --headless

# Complete auth on another device
# CCS detects when token is cached

​
Multi-Account Issues

# List all accounts to verify state
ccs codex --accounts

# Clear and re-authenticate
ccs codex --logout
ccs codex --auth

​
Token Expiry

Tokens refresh automatically. If refresh fails: 
# Re-authenticate
ccs codex --auth

​
Cost Information

Plan Access: Use gpt-5.4 for the default Codex path and gpt-5.4-mini for the fast path. gpt-5.5 and older models such as gpt-5.3-codex require paid Codex access, while gpt-5.3-codex-spark is a research preview model for ChatGPT Pro subscribers. Usage Limits: Subject to OpenAI’s rate limits and fair use policy

​
Next Steps

Multi-Account Setup

Manage multiple Codex accounts

Dashboard Config

Configure via web interface