This is the full developer documentation for claude-code-proxy # What is claude-code-proxy? > Run Claude Code with Codex, Kimi, Grok, or Cursor Agent through one local Anthropic-compatible proxy. claude-code-proxy lets you use Claude Code with Codex, Kimi, Grok, or Cursor Agent. Start one local app, choose a model, and keep working in the Claude Code interface you already know. Your coding interface **Claude Code** → Local bridge **claude-code-proxy** Chooses the provider from your model → Supported providers CodexKimiGrokCursor Agent ## Why use it? [Section titled “Why use it?”](#why-use-it) * **Keep the Claude Code experience.** Skills, tools, hooks, subagents, IDE integrations, and the terminal interface stay on the client side. * **Use subscription-backed providers.** Authenticate with supported consumer accounts instead of putting provider API keys into Claude Code. * **Switch providers by model.** A single proxy process routes every request from its model ID. * **Use Claude Code normally.** Tools, images, streaming responses, and reasoning work across supported providers. * **See what is happening.** The monitor TUI shows sessions, requests, errors, models, token use, and throughput. Structured logs and optional traffic captures support deeper diagnosis.  ## Next steps [Section titled “Next steps”](#next-steps) Start with the [short Codex setup](/getting-started/), compare the [supported providers](/providers/choosing-a-provider/), or read [how requests flow](/how-it-works/). # Getting started > Install claude-code-proxy, authenticate with Codex, start the server, and open one working Claude Code session. This path gets one Codex-backed Claude Code session working. See [Choosing a provider](/providers/choosing-a-provider/) for Kimi, Grok, and Cursor Agent. ## 1. Install [Section titled “1. Install”](#1-install) On macOS or Linux with Homebrew: ```sh brew install raine/claude-code-proxy/claude-code-proxy ``` Or use the release installer: ```sh curl -fsSL https://raw.githubusercontent.com/raine/claude-code-proxy/main/scripts/install.sh | bash ``` Windows archives and binaries for every supported platform are on the [GitHub releases page](https://github.com/raine/claude-code-proxy/releases). ## 2. Sign in to Codex [Section titled “2. Sign in to Codex”](#2-sign-in-to-codex) Use a **ChatGPT Plus or Pro account**, not an OpenAI API account: ```sh claude-code-proxy codex auth login ``` For SSH or another headless environment, use `claude-code-proxy codex auth device` instead. ## 3. Start the proxy [Section titled “3. Start the proxy”](#3-start-the-proxy) Keep this process running: ```sh claude-code-proxy serve ``` It listens on `127.0.0.1:18765`. In an interactive terminal it opens the monitor TUI. ## 4. Start Claude Code [Section titled “4. Start Claude Code”](#4-start-claude-code) Open another terminal and run: ```sh ANTHROPIC_BASE_URL=http://127.0.0.1:18765 \ ANTHROPIC_AUTH_TOKEN=unused \ ANTHROPIC_MODEL=gpt-5.6-sol[1m] \ ANTHROPIC_SMALL_FAST_MODEL=gpt-5.6-luna[1m] \ CLAUDE_CODE_AUTO_COMPACT_WINDOW=272000 \ CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \ CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 \ claude ``` Send a prompt. The request appears in the monitor and the response streams into Claude Code. The `[1m]` suffix is a Claude Code compaction hint. The proxy removes it before the upstream request. The explicit 272,000 token auto-compact window keeps the local threshold within the ChatGPT context limit used by these models. For persistent settings, provider switching, and model discovery, continue to [Configure Claude Code](/using/configure-claude-code/) and [Models and routing](/using/models-and-routing/). # How it works > Follow authentication, routing, protocol translation, streaming, session state, and diagnostics through claude-code-proxy. claude-code-proxy exposes an Anthropic-compatible HTTP surface to Claude Code and translates each request into the selected provider’s native protocol. **Claude Code**POST /v1/messages\ Anthropic SSE → **Proxy pipeline**route model\ refresh auth\ translate events → `Codex Responses``Kimi Chat Completions``Grok Responses``Cursor Connect` ## Request lifecycle [Section titled “Request lifecycle”](#request-lifecycle) 1. Claude Code sends an Anthropic Messages request to `/v1/messages`. 2. The registry normalizes a trailing `[1m]`, resolves aliases, and selects a provider from the model ID. 3. The provider loads its proxy-owned credential and refreshes an expiring access token when needed. 4. The request translator maps system content, user and assistant messages, images, tools, tool results, thinking controls, and output settings into the upstream shape. 5. The upstream stream is reduced into typed text, thinking, tool, usage, and completion events. 6. The proxy emits Anthropic SSE events or accumulates a non-streaming Anthropic response. 7. The monitor, JSONL logger, and optional traffic capture record operational details. ## Authentication boundary [Section titled “Authentication boundary”](#authentication-boundary) Each provider login belongs to claude-code-proxy. The proxy does not read native Codex, Grok, or Cursor Agent credentials. Credentials live in the platform credential store described in [Files and storage](/reference/files-and-storage/). Incoming `ANTHROPIC_AUTH_TOKEN` values are accepted for client compatibility and are not used as upstream credentials. ## Routing boundary [Section titled “Routing boundary”](#routing-boundary) Routing happens per request, not per server process. Codex IDs, Kimi IDs, Grok IDs, Cursor prefixes, and configured Anthropic-style aliases can share one listener. Unknown model IDs return HTTP 400 with the supported catalog. ## Session state [Section titled “Session state”](#session-state) Claude Code sends `x-claude-code-session-id`. The proxy uses it for monitor grouping and provider features that need continuity. Cursor conversation IDs, optional Codex `previous_response_id`, and optional Codex server compaction state live in memory. A proxy restart clears that state and portable Claude Code history remains the fallback. ## Count tokens [Section titled “Count tokens”](#count-tokens) `POST /v1/messages/count_tokens` performs a local estimate with `gpt-tokenizer` and the `o200k_base` encoding. It supports Claude Code’s compaction decisions without an upstream request. See [HTTP API](/reference/http-api/) for route contracts and [Compatibility and limitations](/reference/compatibility-and-limitations/) for translation boundaries. # Choosing a provider > Compare claude-code-proxy providers by account, protocol, models, reasoning, multimodal input, tools, and operational tradeoffs. One `serve` process supports every provider. Choose based on the account you have, model access, and the capabilities your work needs. | Provider | Account | Upstream protocol | Model selection | Notable capabilities | | ---------------------------------------- | ------------------------------ | ------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | [Codex](/providers/codex/) | ChatGPT Plus or Pro | OpenAI Responses over WebSocket or HTTP SSE | Named Codex catalog, `-fast` variants | Function tools, image input, hosted web search, reasoning summaries, optional native Responses route | | [Kimi](/providers/kimi/) | kimi.com with Kimi Code access | OpenAI-style chat completions | `kimi-for-coding` and aliases | Function tools, reasoning, image and video input | | [Grok](/providers/grok/) | grok.com | Responses API | `grok-composer-2.5-fast`, `grok-4.5` | Function tools, reasoning, web search, X search, citations | | [Cursor Agent](/providers/cursor-agent/) | Cursor account | HTTP/2 Connect stream | Cursor modes and `cursor:` prefixes | Dynamic model catalog, effort variants, images, plan and ask modes, session continuation | ## Practical guidance [Section titled “Practical guidance”](#practical-guidance) * Start with **Codex** when you have a ChatGPT subscription and want the most developed Claude Code translation path. * Choose **Kimi** for the Kimi Code model and multimodal coding input. * Choose **Grok** for Grok models and hosted web or X search. * Choose **Cursor Agent** when you want Cursor’s model catalog and agent modes. It depends on an installed Cursor Agent bundle for protobuf schemas. ## Shared behavior [Section titled “Shared behavior”](#shared-behavior) All providers route by model ID, use proxy-owned credentials, refresh tokens when supported, stream responses, translate Claude Code tool definitions, and report failures through the same Anthropic-shaped API. **Account policy matters.** Provider subscriptions, model access, regional availability, rate limits, and rules for unofficial clients can change. Review the terms for your account before using a provider through the proxy. Use `claude-code-proxy models` for the current compact catalog and `claude-code-proxy models --full` for all advertised aliases. The [Models and routing](/using/models-and-routing/) page explains aliases and discovery. # Codex > Configure ChatGPT Codex authentication, models, reasoning, tools, images, transports, continuation, compaction, and native Responses passthrough. Codex uses the ChatGPT subscription Responses endpoint at `https://chatgpt.com/backend-api/codex/responses`. ## Account and authentication [Section titled “Account and authentication”](#account-and-authentication) Sign in with a **ChatGPT Plus or Pro account**, not OpenAI API credentials. ```sh claude-code-proxy codex auth login # Headless device-code flow claude-code-proxy codex auth device claude-code-proxy codex auth status ``` The proxy owns its tokens and does not read native Codex CLI credentials. It refreshes expiring access tokens with a single-flight guard. See [Files and storage](/reference/files-and-storage/) for credential locations. ## Models and fast mode [Section titled “Models and fast mode”](#models-and-fast-mode) Use `claude-code-proxy models` as the current catalog. Model access depends on your ChatGPT account. A model rejected by the subscription produces the upstream error verbatim. Append `-fast` to any registered Codex model to request `service_tier: "priority"`. For example, `gpt-5.6-sol-fast` selects `gpt-5.6-sol` with fast service. `CCP_CODEX_SERVICE_TIER` or `codex.serviceTier` takes precedence. ## Reasoning [Section titled “Reasoning”](#reasoning) Claude Code’s `/effort` value maps to Codex `reasoning.effort`: `low`, `medium`, `high`, `xhigh`, or `max`. A proxy override can also force `none`. When reasoning is enabled, the proxy requests an automatic reasoning summary and translates summary deltas into Claude Code thinking blocks. Codex may omit a summary for a simple prompt. `CCP_CODEX_REASONING_SUMMARY=off` suppresses summaries while preserving effort and encrypted continuation content. Claude Code summary compaction requests are capped at low effort by default because they perform extraction over a large transcript. `CCP_COMPACT_EFFORT=off` disables the cap, `none` removes reasoning, and another valid effort sets a different maximum. The cap never raises effort. ## Tools and multimodal input [Section titled “Tools and multimodal input”](#tools-and-multimodal-input) * Claude function tools and tool results map to Responses API function calls and outputs. * Claude Code hosted web search maps to Codex `web_search`, including supported domain filters and forced tool choice. * Top-level base64 user images map to `input_image`. * Supported base64 images nested in tool results also map to `input_image`. * Remote image URLs, malformed images, and unsupported tool-result image forms remain textual placeholders. * Strict JSON schema output maps to Responses `text.format`. ## Transport and continuation [Section titled “Transport and continuation”](#transport-and-continuation) WebSocket is the default transport. Set `CCP_CODEX_TRANSPORT=http` for HTTP SSE, or `auto` to use WebSocket with HTTP fallback only when setup fails before a request is sent. `CCP_CODEX_PREVIOUS_RESPONSE_ID=1` enables append-only WebSocket continuation. It reuses a session connection and sends `previous_response_id` only when the translated request shape and transcript extension are safe. State is in memory, keyed by Claude Code session ID. ## Server compaction [Section titled “Server compaction”](#server-compaction) Codex server compaction is opt-in: ```sh CCP_CODEX_SERVER_COMPACTION=1 claude-code-proxy serve ``` At a Claude Code compaction boundary, the proxy requests native Codex compaction, keeps the encrypted item in memory for the matching session and model, and anchors replay to Claude Code’s portable summary. Branches, restarts, model changes, malformed responses, expiry, or memory limits fall back to portable history. State can remain in memory for up to 30 minutes. The boundary adds one Codex request. Structured events named `server_compaction_triggered`, `server_compaction_completed`, and `server_compaction_failed` report its outcome. ## Native Responses API [Section titled “Native Responses API”](#native-responses-api) `CCP_CODEX_RESPONSES_API=1` enables `POST /v1/responses`. The proxy replaces incoming credentials with stored Codex auth and preserves native JSON or SSE response bodies. This route covers registered Codex models. Images API, response retrieval or deletion, and WebSocket ingress are outside its scope. See [Configuration](/reference/configuration/) for every Codex setting and [Troubleshooting](/using/troubleshooting/) for auth, model, and transport failures. # Cursor Agent > Configure Cursor authentication, dynamic models, plan and ask modes, effort variants, images, session continuation, tool bridging, and protobuf discovery. Cursor uses Cursor Agent’s HTTP/2 full-duplex Connect protocol at `https://api2.cursor.sh/agent.v1.AgentService/Run`. ## Account and authentication [Section titled “Account and authentication”](#account-and-authentication) Use a **Cursor account**: ```sh claude-code-proxy cursor auth login claude-code-proxy cursor auth status ``` The browser flow stores proxy-owned tokens. It does not read Cursor Agent’s Keychain or `auth.json`. `CCP_CURSOR_AUTH_TOKEN` can supply a bearer token directly to the proxy process. ## Cursor Agent dependency [Section titled “Cursor Agent dependency”](#cursor-agent-dependency) The provider speaks Cursor’s protocol directly but loads generated protobuf classes from an installed Cursor Agent `index.js` bundle. Auto-detection checks common installations. Set `CCP_CURSOR_AGENT_BUNDLE` when the bundle cannot be found. ## Models and modes [Section titled “Models and modes”](#models-and-modes) Prefer prefixed IDs: * `cursor:` runs the named Cursor model in agent mode. * `cursor-plan:` uses plan mode. * `cursor-ask:` uses ask mode. Legacy IDs such as `cursor`, `cursor-plan`, `cursor-ask`, `composer-2.5`, and `composer-2.5-fast` remain available. Prefixes avoid collisions, so `gpt-5.2` can route to Codex while `cursor:gpt-5.2` routes to Cursor. The provider reads Cursor Agent’s current model catalog at runtime. Use: ```sh claude-code-proxy models --full ``` Unknown future IDs are accepted through `cursor:`. ## Effort mapping [Section titled “Effort mapping”](#effort-mapping) Claude Code’s `/effort` selects matching Cursor catalog variants when available. For example, `cursor:gpt-5.5` plus high effort can resolve to `gpt-5.5-high`. Explicit effort suffixes are preserved. Fast suffixes remain when the catalog supports them, and models without effort variants stay unchanged. ## Tools and multimodal input [Section titled “Tools and multimodal input”](#tools-and-multimodal-input) * System prompts, messages, and tool definitions are rendered into the Cursor agent prompt. * Base64 user images become Cursor selected images. * Text, thinking, plan mode, ask mode, and usage stream back to Claude Code. * The native tool bridge recognizes Cursor requests for `Read`, `Write`, and `Bash` when matching Claude tools are advertised and a Claude Code session ID is present. It pauses the stream, emits an Anthropic tool call, accepts the next tool result, and resumes stored events. * Other Cursor workspace callbacks and native tool forms do not have a general Claude tool bridge. ## Session continuation [Section titled “Session continuation”](#session-continuation) The proxy maps `x-claude-code-session-id` to a Cursor conversation ID in memory. Request metadata can resume a known Cursor chat through `cursor_chat_id`, `cursorChatId`, `cursor_resume`, or `cursorResume`. A proxy restart clears the in-memory mapping. Metadata can also choose a mode per request: ```json { "metadata": { "cursor_mode": "plan" } } ``` ## Configuration and troubleshooting [Section titled “Configuration and troubleshooting”](#configuration-and-troubleshooting) `CCP_CURSOR_BASE_URL`, `CCP_CURSOR_CLIENT_VERSION`, and `CCP_CURSOR_AGENT_BUNDLE` override protocol details. If authentication expires, Cursor requests return 401 and require another login. If startup or requests report protobuf discovery errors, run `cursor-agent --version` to confirm it is installed and set the bundle path explicitly. See [Compatibility and limitations](/reference/compatibility-and-limitations/) for the supported tool boundary. # Grok > Configure grok.com authentication, Grok models, reasoning, function tools, hosted web and X search, citations, and provider overrides. Grok uses the Responses endpoint at `https://cli-chat-proxy.grok.com/v1/responses`. ## Account and authentication [Section titled “Account and authentication”](#account-and-authentication) Use a **grok.com account**. Browser login uses S256 PKCE through `auth.x.ai` and an ephemeral loopback callback: ```sh claude-code-proxy grok auth login ``` For a headless host, use the device-code flow: ```sh claude-code-proxy grok auth device claude-code-proxy grok auth status ``` The proxy owns and refreshes its Grok tokens. It does not read `~/.grok/auth.json`. ## Models [Section titled “Models”](#models) The registered IDs are `grok-composer-2.5-fast` and `grok-4.5`. Account and regional access can vary. Use the same concrete Grok ID for `ANTHROPIC_MODEL` and `ANTHROPIC_SMALL_FAST_MODEL`. ```sh ANTHROPIC_MODEL=grok-4.5 \ ANTHROPIC_SMALL_FAST_MODEL=grok-4.5 \ claude --model grok-4.5 ``` ## Reasoning and tools [Section titled “Reasoning and tools”](#reasoning-and-tools) The proxy translates Claude messages, function tools, tool results, thinking controls, token usage, and streaming events. Grok reasoning text appears as Claude Code thinking blocks. Claude Code hosted search tools map to Grok-native tools: * General web queries use hosted web search. * X queries use hosted `x_search`. * Citations and search usage return in Anthropic-compatible content and usage fields. ## Multimodal support [Section titled “Multimodal support”](#multimodal-support) Grok support in claude-code-proxy focuses on text, reasoning, function tools, and hosted search. Treat image and other media behavior as unsupported unless the current source and tests explicitly cover it. ## Configuration [Section titled “Configuration”](#configuration) * `CCP_GROK_BASE_URL` or `grok.baseUrl` changes the API base URL. * `CCP_GROK_CLIENT_VERSION` or `grok.clientVersion` changes the client version header. See [Configuration](/reference/configuration/) for defaults. ## Limitations and troubleshooting [Section titled “Limitations and troubleshooting”](#limitations-and-troubleshooting) A successful login does not guarantee every model is enabled for the account or region. Model rejection and upstream errors are surfaced to Claude Code. Use `grok auth status` for token state, inspect the failed request in the monitor, and use the structured log or error capture for the full redacted response. # Kimi > Configure Kimi Code authentication, model aliases, reasoning effort, tools, images, video, token refresh, and provider settings. Kimi uses the OpenAI-style chat completions endpoint at `https://api.kimi.com/coding/v1/chat/completions`. ## Account and authentication [Section titled “Account and authentication”](#account-and-authentication) Use a **kimi.com account with Kimi Code access**. Authentication is an RFC 8628 device-code flow: ```sh claude-code-proxy kimi auth login claude-code-proxy kimi auth status ``` The login prints a verification URL and user code, then polls until authorization completes. Access tokens have a short lifetime and are refreshed before expiry. A persistent device ID is created with the Kimi credential because it is bound into the issued token. ## Model selection [Section titled “Model selection”](#model-selection) The upstream wire model is `kimi-for-coding`, displayed by Kimi tooling as Kimi K2.6. The proxy also accepts `kimi-k2.6` and `k2.6` as aliases. Use `[1m]` as a Claude Code compaction hint only when the actual upstream context and your chosen threshold support it. ```sh ANTHROPIC_MODEL=kimi-for-coding[1m] ANTHROPIC_SMALL_FAST_MODEL=kimi-for-coding[1m] ``` ## Reasoning [Section titled “Reasoning”](#reasoning) Claude Code’s `/effort` setting maps to Kimi `reasoning_effort` at `low`, `medium`, or `high`. Returned reasoning streams into Claude Code thinking blocks. If the Anthropic request disables thinking, the proxy omits both Kimi reasoning controls. ## Tools and multimodal input [Section titled “Tools and multimodal input”](#tools-and-multimodal-input) * Claude function tools and tool choice map to Kimi chat-completions tools. * Tool calls and tool results round-trip through Anthropic content blocks. * Image input maps to Kimi image content. * Images inside tool results map to `image_url` parts in tool messages. * Supported video input maps to Kimi video content. ## Configuration [Section titled “Configuration”](#configuration) `CCP_KIMI_BASE_URL`, `CCP_KIMI_OAUTH_HOST`, and `CCP_KIMI_USER_AGENT` provide explicit endpoint and client overrides. `CCP_USER_AGENT` is the fallback user-agent override. These settings are intended for compatibility and controlled debugging. See [Configuration](/reference/configuration/) for defaults and file keys. ## Limitations and troubleshooting [Section titled “Limitations and troubleshooting”](#limitations-and-troubleshooting) Account access and rate limits come from Kimi. HTTP 429 is returned to Claude Code with `retry-after`. If login succeeds but requests return 401, inspect token expiry with `kimi auth status`, then log in again. Preserve the Kimi device ID alongside the credential when copying a configuration directory. The proxy estimates count-tokens locally rather than asking Kimi. See [Compatibility and limitations](/reference/compatibility-and-limitations/) for shared boundaries. # Changelog > Release notes for claude-code-proxy. ## Unreleased [Section titled “Unreleased”](#unreleased) * The monitor shows active native Codex compaction requests with a dedicated `compacting` status. ## v0.1.24 (2026-07-23) [Section titled “v0.1.24 (2026-07-23)”](#v0124-2026-07-23) * Codex optionally preserves conversation continuity across Claude Code compaction boundaries with native encrypted compaction artifacts. Enable it with `codex.serverCompaction` or `CCP_CODEX_SERVER_COMPACTION`. * Native OpenAI Responses clients can use `POST /v1/responses` with existing Codex authentication, including JSON responses, SSE streaming, and automatic token refresh. Enable the endpoint with `codex.responsesApi` or `CCP_CODEX_RESPONSES_API=1`; it is disabled by default. ## v0.1.23 (2026-07-22) [Section titled “v0.1.23 (2026-07-22)”](#v0123-2026-07-22) * Codex WebSocket streaming handles pooled connections and HTTP fallback more reliably, preventing concurrent requests from blocking each other or sending the same request twice. * Codex errors preserve upstream status codes and optional retry timing, with clearer permission failures and safer WebSocket handshake diagnostics. * Codex streaming limits oversized events and error responses, preventing malformed or stalled upstream responses from consuming unbounded memory. ## v0.1.22 (2026-07-20) [Section titled “v0.1.22 (2026-07-20)”](#v0122-2026-07-20) * Grok accepts request metadata and tool-result references sent by current Claude Code versions while continuing to reject malformed and unknown fields. ([#56](https://github.com/raine/claude-code-proxy/pull/56)) * Gateway model discovery lists every configured provider model and Claude-style alias through `GET /v1/models`, making supported aliases available in Claude Code’s model picker. ([#60](https://github.com/raine/claude-code-proxy/issues/60), [#61](https://github.com/raine/claude-code-proxy/pull/61)) * Codex preserves supported base64 images in tool results while keeping mixed text, image, error, and fallback content in its original order. ([#59](https://github.com/raine/claude-code-proxy/pull/59)) * Codex requests continue after the included usage limit when account credits remain available. ([#68](https://github.com/raine/claude-code-proxy/pull/68)) * Codex compaction requests cap reasoning effort at `low` to reduce latency and reasoning-token usage. `CCP_COMPACT_EFFORT` can choose a different cap or disable the behavior. ([#67](https://github.com/raine/claude-code-proxy/pull/67)) ## v0.1.21 (2026-07-15) [Section titled “v0.1.21 (2026-07-15)”](#v0121-2026-07-15) * The monitor shows session token activity trends at common terminal widths, making throughput history visible without an extra-wide window. ## v0.1.20 (2026-07-15) [Section titled “v0.1.20 (2026-07-15)”](#v0120-2026-07-15) * The monitor reliably shows project names for Claude Code sessions and keeps them visible as requests are sequenced. * Keyboard navigation scrolls session and recent-request tables to keep the selected row visible. * Pressing `q` asks for confirmation before gracefully shutting down the proxy. * Compact monitor layouts show more project, provider, model, effort, and token details without requiring a wider terminal. ## v0.1.19 (2026-07-15) [Section titled “v0.1.19 (2026-07-15)”](#v0119-2026-07-15) * The monitor shows project and session context at more terminal widths while preserving key request details in narrower layouts. ## v0.1.18 (2026-07-15) [Section titled “v0.1.18 (2026-07-15)”](#v0118-2026-07-15) * Codex preserves encrypted reasoning across turns, improving continuity when conversation history is replayed. ([#52](https://github.com/raine/claude-code-proxy/pull/52)) * The new `demo` command opens the interactive monitor with simulated traffic, without starting a proxy server or requiring provider credentials. * Session rows show project names and output-token activity over time, making concurrent sessions and usage bursts easier to identify. * Monitor tables adapt more consistently across terminal sizes and keep important request details readable in compact layouts. * The monitor stays visible during graceful shutdown and shows progress until the proxy finishes draining connections. ## v0.1.17 (2026-07-14) [Section titled “v0.1.17 (2026-07-14)”](#v0117-2026-07-14) * The proxy can listen on a configurable IP address through `CCP_BIND_ADDRESS` or `bindAddress`, enabling protected access from containers and remote hosts. ([#48](https://github.com/raine/claude-code-proxy/pull/48)) * Model names with context-window hints such as `[1m]` route correctly across providers. ([#50](https://github.com/raine/claude-code-proxy/pull/50)) * The monitor reports more accurate output rates by measuring generation time and excluding requests without complete usage and timing data. ## v0.1.16 (2026-07-13) [Section titled “v0.1.16 (2026-07-13)”](#v0116-2026-07-13) * GPT-5.6 Luna requests work without a custom User-Agent instead of failing with a model unavailable error. ([#45](https://github.com/raine/claude-code-proxy/issues/45)) * Canceled or replaced Codex prompts cannot interrupt later turns with stale continuation state. * GPT-5.6 setup examples use a 272K compaction window to stay within the current ChatGPT context limit. * Homebrew installations can run the proxy at login as a background service with `brew services start claude-code-proxy`. ([#44](https://github.com/raine/claude-code-proxy/pull/44)) ## v0.1.15 (2026-07-12) [Section titled “v0.1.15 (2026-07-12)”](#v0115-2026-07-12) * Codex function tools preserve optional parameters, preventing unintended tool arguments and incorrect agent isolation choices. ([#43](https://github.com/raine/claude-code-proxy/issues/43)) * Forced Codex web searches return live results while preserving allowed and blocked domain filters. ([#26](https://github.com/raine/claude-code-proxy/issues/26)) * Codex credentials are stored and refreshed independently from the native Codex CLI, preventing either application from invalidating the other’s login. Users who relied on the native Codex login must sign in to the proxy once after upgrading. * [Expanded guidance](https://github.com/raine/claude-code-proxy/#switching-models-and-backends) explains how to switch models within the proxy and how to switch between the proxy and direct Anthropic. ## v0.1.14 (2026-07-12) [Section titled “v0.1.14 (2026-07-12)”](#v0114-2026-07-12) * Codex hosted web searches work when Claude Code routes them through the Luna small model. ([#26](https://github.com/raine/claude-code-proxy/issues/26), [#35](https://github.com/raine/claude-code-proxy/pull/35)) * Codex context-window errors trigger Claude Code’s compaction flow instead of ending the request. ([#29](https://github.com/raine/claude-code-proxy/pull/29)) * Codex requests fall back to HTTP after WebSocket handshake failures while preserving live streaming for established connections. ([#39](https://github.com/raine/claude-code-proxy/pull/39)) * Codex HTTP and WebSocket failures retain upstream status codes and error details, making failures clearer and more actionable. ([#40](https://github.com/raine/claude-code-proxy/pull/40)) ## v0.1.13 (2026-07-12) [Section titled “v0.1.13 (2026-07-12)”](#v0113-2026-07-12) * Grok users can sign in on headless hosts with `grok auth device`. ([#38](https://github.com/raine/claude-code-proxy/pull/38)) * Grok tool calls accept Claude Code’s prompt-cache markers, preventing errors when switching to Grok during a tool-using session. ([#37](https://github.com/raine/claude-code-proxy/pull/37)) * Codex hosted web searches return their result links and citations to Claude Code instead of appearing to produce zero results. ([#10](https://github.com/raine/claude-code-proxy/issues/10)) * Codex authentication refresh is coordinated across concurrent requests and automatically recovers live WebSocket requests after credentials expire. * Codex requests recover more reliably from temporary upstream failures, connection resets, overloads, and long-running responses. ## v0.1.12 (2026-07-12) [Section titled “v0.1.12 (2026-07-12)”](#v0112-2026-07-12) * Codex hosted web searches work with GPT-5.6 models instead of failing with an unsupported tool error. ([#26](https://github.com/raine/claude-code-proxy/issues/26), [#35](https://github.com/raine/claude-code-proxy/pull/35)) * Codex WebSocket connection timeouts are retried automatically, reducing interrupted requests. ## v0.1.11 (2026-07-11) [Section titled “v0.1.11 (2026-07-11)”](#v0111-2026-07-11) * Grok subscriptions can power Claude Code through browser login, with support for Grok 4.5 and Composer 2.5 Fast, streaming, thinking, tools, and token counts. * Codex WebSocket requests recover from handshake failures and stay marked active until the full response body finishes streaming. * The monitor shows local timestamps, clearer request status and detail indicators, more compact columns, arrow-key pane navigation, and an uncluttered display. * Forward Claude Code’s `max` effort as Codex `reasoning.effort: "max"` so GPT-5.6 can use its highest supported reasoning level instead of silently receiving `xhigh`. ([#28](https://github.com/raine/claude-code-proxy/pull/28)) ## v0.1.10 (2026-07-10) [Section titled “v0.1.10 (2026-07-10)”](#v0110-2026-07-10) * Claude Code requests using Opus 4.8, Sonnet 5, and Fable 5 model names can route through Codex ## v0.1.9 (2026-07-10) [Section titled “v0.1.9 (2026-07-10)”](#v019-2026-07-10) * Claude model aliases use the matching GPT-5.6 tier through Codex: Haiku uses Luna, Sonnet uses Terra, and Opus uses Sol. * GPT-5.6 Codex requests preserve reasoning context and support system guidance and tools through the Responses Lite API. * The dashboard shows requested effort and resolved upstream models, making routing decisions easier to inspect. ## v0.1.8 (2026-07-09) [Section titled “v0.1.8 (2026-07-09)”](#v018-2026-07-09) * Codex requests can use `gpt-5.6-sol`, `gpt-5.6-terra`, and `gpt-5.6-luna`, including `-fast` variants. * The default Codex setup uses `gpt-5.6-sol` with `gpt-5.6-luna` as the small fast model and a 372K compaction window. ## v0.1.7 (2026-07-06) [Section titled “v0.1.7 (2026-07-06)”](#v017-2026-07-06) * Codex `Read` tool calls get clearer offset guidance and recover from clearly invalid large offsets, reducing stalled sessions caused by mistaken line-number reads. * The monitor keeps request lists accurate when a client disconnects or abandons a request. ## v0.1.5 (2026-07-03) [Section titled “v0.1.5 (2026-07-03)”](#v015-2026-07-03) * Claude Code’s `xhigh` and `max` effort settings now work with Codex and Kimi requests instead of being rejected or downgraded unexpectedly. ([#20](https://github.com/raine/claude-code-proxy/pull/20)) * Codex receives clearer `Read` tool guidance for line offsets, reducing incorrect follow-up reads on large files. ([#22](https://github.com/raine/claude-code-proxy/pull/22)) ## v0.1.4 (2026-07-01) [Section titled “v0.1.4 (2026-07-01)”](#v014-2026-07-01) * Codex WebSocket streams recover when a pooled continuation connection closes before the final response, retrying the turn with full context instead of failing the session. ## v0.1.3 (2026-07-01) [Section titled “v0.1.3 (2026-07-01)”](#v013-2026-07-01) * Codex WebSocket streams deliver live text and reasoning progress while reusing pooled session continuations to reduce repeated upstream input. * Codex stream recovery handles retryable startup failures, context-window errors, stale continuations, completed tool-call disconnects, stalled `Read` arguments, quiet upstream turns, and completed-turn stop reasons. * Codex gateway requests and tool result translation use accepted payload shapes and preserve omitted-block markers for malformed text and image result content. ## v0.1.2 (2026-06-30) [Section titled “v0.1.2 (2026-06-30)”](#v012-2026-06-30) * Codex WebSocket continuations recover from streams that only deliver rate limit or control events, preventing Claude Code sessions from waiting indefinitely on a stalled upstream response. ## v0.1.1 (2026-06-30) [Section titled “v0.1.1 (2026-06-30)”](#v011-2026-06-30) * Codex reasoning summaries are now surfaced as thinking blocks in the response stream, so you can see the model’s reasoning in your Claude Code session when reasoning effort is enabled. Set `codex.reasoningSummary` or `CCP_CODEX_REASONING_SUMMARY` to `off` or `none` to suppress summary display while keeping reasoning effort active. (Thanks @samot-gc!) * Codex transport errors (WebSocket connection failures, etc.) now show the actual error message instead of a generic “Upstream error”, making connection issues easier to diagnose. ## v0.1.0 (2026-06-30) [Section titled “v0.1.0 (2026-06-30)”](#v010-2026-06-30) * Ships the native Rust implementation as the release binary. * Adds the default monitor TUI for `serve`. * Improves diagnostics with failed-response captures and clearer monitor request details. ## v0.0.22 (2026-06-24) [Section titled “v0.0.22 (2026-06-24)”](#v0022-2026-06-24) * Codex requests now retry more transient stream and overload failures, making temporary upstream errors less likely to interrupt Claude Code sessions. ([#15](https://github.com/raine/claude-code-proxy/issues/15)) * Codex can now recover stalled `Read` tool calls that previously left Claude Code waiting on incomplete streamed arguments. * Cursor tool calls are recovered more reliably when Cursor returns XML-style tool use, improving compatibility with Claude Code tools. * Cursor auth can now be isolated with `CCP_CONFIG_DIR`, so separate proxy configs can keep separate Cursor logins. * Cursor `composer-2.5` requests now stay in non-fast mode unless fast mode is explicitly requested. ([#17](https://github.com/raine/claude-code-proxy/issues/17), [#18](https://github.com/raine/claude-code-proxy/pull/18)) ## v0.0.21 (2026-06-15) [Section titled “v0.0.21 (2026-06-15)”](#v0021-2026-06-15) * Forced Codex web search requests now use hosted web search correctly, fixing repeated upstream `Tool choice 'function' not found in 'tools' parameter.` errors. ([#10](https://github.com/raine/claude-code-proxy/issues/10)) ## v0.0.20 (2026-06-15) [Section titled “v0.0.20 (2026-06-15)”](#v0020-2026-06-15) * Cursor’s generic `cursor`, `cursor-agent`, `cursor-plan`, and `cursor-ask` aliases now use Cursor default model selection instead of forcing Composer 2.5 fast mode. ## v0.0.19 (2026-06-14) [Section titled “v0.0.19 (2026-06-14)”](#v0019-2026-06-14) * Codex now supports Claude Code hosted web search through Codex’s native web search, including domain filters and search usage accounting. ([#10](https://github.com/raine/claude-code-proxy/issues/10)) ## v0.0.18 (2026-06-09) [Section titled “v0.0.18 (2026-06-09)”](#v0018-2026-06-09) * Cursor sessions now stop heartbeat traffic after streams close, reducing stray connection errors. * Codex now treats runtime system messages as developer guidance instead of assistant output, preventing Claude Code reminders from being repeated. ## v0.0.17 (2026-06-08) [Section titled “v0.0.17 (2026-06-08)”](#v0017-2026-06-08) * Added Cursor Agent as a provider, including login, model selection, ask mode, plan mode, and session continuation. * Cursor users can select models from the Cursor catalog with `cursor:`, `cursor-plan:`, and `cursor-ask:` aliases. ## v0.0.16 (2026-06-02) [Section titled “v0.0.16 (2026-06-02)”](#v0016-2026-06-02) * Codex now uses WebSocket transport by default * Codex sessions can opt in to append-only continuation with `previous_response_id`, reducing repeated upload size on compatible turns. * `CCP_TRAFFIC_LOG=1` writes redacted per-request traffic captures to help debug sessions. * Codex request logging now includes size summaries and image warnings to make compaction and large requests easier to diagnose. * README guidance for Codex context limits and `[1m]` model suffixes is clearer. ## v0.0.15 (2026-05-30) [Section titled “v0.0.15 (2026-05-30)”](#v0015-2026-05-30) * Anthropic requests that omit `stream` now receive JSON responses, fixing Claude Code `/model` validation through the proxy. ## v0.0.14 (2026-05-30) [Section titled “v0.0.14 (2026-05-30)”](#v0014-2026-05-30) * Codex streaming now stays responsive during long `Read` tool calls by sending keepalive pings while tool arguments are buffered. * Truncated Codex streams now return a clear error instead of appearing to finish successfully with incomplete tool calls. * Stalled Codex requests now time out and retry when response headers never arrive, with clearer diagnostics for slow upstream responses. ## v0.0.13 (2026-05-14) [Section titled “v0.0.13 (2026-05-14)”](#v0013-2026-05-14) * Windows users can now download prebuilt `windows-amd64` and `windows-arm64` release archives. ## v0.0.12 (2026-05-12) [Section titled “v0.0.12 (2026-05-12)”](#v0012-2026-05-12) * Codex requests can now use `gpt-5.3-codex-spark` as a supported model. ([#14](https://github.com/raine/claude-code-proxy/pull/14)) ## v0.0.11 (2026-05-12) [Section titled “v0.0.11 (2026-05-12)”](#v0011-2026-05-12) * Claude-style aliases such as `haiku`, `sonnet`, and `opus` now default to Codex while still following the provider already active in the current Claude Code session. * Mixed Codex and Kimi sessions now keep background alias and token-count requests on the right provider instead of unexpectedly switching providers. * Tool results with images, errors, or unsupported blocks are handled more safely, reducing malformed upstream requests. ## v0.0.10 (2026-05-06) [Section titled “v0.0.10 (2026-05-06)”](#v0010-2026-05-06) * Codex requests can now use `codex.serviceTier` or `CCP_CODEX_SERVICE_TIER` to request a service tier; `fast` is sent upstream as `priority`. * Codex model names can now include `-fast`, such as `gpt-5.4-fast[1m]`, to request fast mode per request without restarting the proxy. * Codex’s upstream endpoint can now be overridden with `codex.baseUrl` or `CCP_CODEX_BASE_URL`. ## v0.0.9 (2026-05-03) [Section titled “v0.0.9 (2026-05-03)”](#v009-2026-05-03) * Kimi debugging overrides now use `CCP_KIMI_OAUTH_HOST` and `CCP_KIMI_BASE_URL`, matching the proxy’s `CCP_` environment variable naming. ## v0.0.8 (2026-04-30) [Section titled “v0.0.8 (2026-04-30)”](#v008-2026-04-30) * Added exponential backoff retry on upstream 429 errors, respecting `Retry-After` headers when present * Added `config.json` as an alternative to environment variables (read from `~/.config/claude-code-proxy/config.json` on macOS, XDG-compliant on Linux) * Made the `originator` and `User-Agent` headers configurable via new env vars (`CCP_CODEX_ORIGINATOR`, `CCP_CODEX_USER_AGENT`, `CCP_KIMI_USER_AGENT`, `CCP_ORIGINATOR`, `CCP_USER_AGENT`) and the config file * Codex now sends a default `User-Agent: claude-code-proxy/` header ## v0.0.7 (2026-04-25) [Section titled “v0.0.7 (2026-04-25)”](#v007-2026-04-25) * Some security hardening inspired by [#5](https://github.com/raine/claude-code-proxy/pull/5) ## v0.0.6 (2026-04-25) [Section titled “v0.0.6 (2026-04-25)”](#v006-2026-04-25) * Added support for `gpt-5.5`, and `opus`/`claude-opus-4-7` aliases now map to `gpt-5.5` instead of `gpt-5.4` * Model names with a `[1m]` context suffix (e.g. `gpt-5.4[1m]`) are now accepted and stripped before routing, so Claude Code’s larger-context model variants work without errors * Documented how to switch between the proxy and direct Anthropic in the README ## v0.0.5 (2026-04-22) [Section titled “v0.0.5 (2026-04-22)”](#v005-2026-04-22) * Added `CCP_CODEX_MODEL` and `CCP_CODEX_EFFORT` environment variables to override the model and reasoning effort for Codex requests ([#2](https://github.com/raine/claude-code-proxy/pull/2)) * Added `claude-sonnet-4-6` and additional model aliases so more Claude-style model names resolve correctly * Improved request logging with usage summaries, time-to-first-byte metrics, and stream completion details for easier debugging * Client disconnections during streaming are now handled gracefully ## v0.0.4 (2026-04-20) [Section titled “v0.0.4 (2026-04-20)”](#v004-2026-04-20) * Kimi: reasoning content is now preserved across turns as Anthropic thinking blocks, so Claude Code sees the model’s thinking and multi-turn reasoning stays coherent * Kimi: thinking is always enabled ## v0.0.3 (2026-04-20) [Section titled “v0.0.3 (2026-04-20)”](#v003-2026-04-20) * Renamed to `claude-code-proxy` to reflect multi-provider support * Added Kimi (kimi.com) as a provider, with device-code login via the install script and support for Kimi’s chat models * Requests are now routed to providers based on the requested model, so a single proxy can serve both Codex and Kimi models simultaneously * Improved token counting accuracy and fixed cached token usage reporting * Added MIT license ## v0.0.2 (2026-04-19) [Section titled “v0.0.2 (2026-04-19)”](#v002-2026-04-19) * Accept Claude-style model aliases (`haiku`, `sonnet`, `opus`, and `claude-*` names), resolving them to the appropriate upstream model so portable configs and subagents work without edits * Fix malformed streamed Read tool arguments that Claude Code would reject when upstream emitted an empty `pages` field ## v0.0.1 (2026-04-19) [Section titled “v0.0.1 (2026-04-19)”](#v001-2026-04-19) Initial release. # Command reference > Canonical claude-code-proxy command syntax for serving, monitoring, listing models, version output, and provider authentication. Running `claude-code-proxy` without a subcommand is equivalent to `claude-code-proxy serve`. ## Global version commands [Section titled “Global version commands”](#global-version-commands) ```sh claude-code-proxy --version claude-code-proxy -v claude-code-proxy version ``` Each prints `claude-code-proxy `. ## `serve` [Section titled “serve”](#serve) ```sh claude-code-proxy serve [--port ] [--no-monitor] ``` Starts the local HTTP proxy and blocks until shutdown. | Option | Behavior | | --------------- | --------------------------------------------------------------------- | | `--port ` | Overrides `PORT`, `config.json`, and the default for this invocation. | | `--no-monitor` | Uses plain output even when stdout is a terminal. | The bind address comes from `CCP_BIND_ADDRESS` or `bindAddress`. Interactive stdout opens the monitor unless `--no-monitor` is present. Non-terminal stdout uses plain mode. ## `demo` [Section titled “demo”](#demo) ```sh claude-code-proxy demo ``` Opens the monitor with deterministic simulated traffic. It does not bind a network port or contact providers. ## `models` [Section titled “models”](#models) ```sh claude-code-proxy models [--full] ``` Prints supported IDs grouped by provider. The default output compacts Cursor’s runtime catalog. `--full` prints every Cursor alias. ## Provider authentication [Section titled “Provider authentication”](#provider-authentication) The command shape is: ```text claude-code-proxy auth ``` | Provider | `login` | `device` | `status` | `logout` | | -------- | -------------------- | ----------- | ---------------------------- | ----------------------- | | `codex` | Browser PKCE | Device code | Account, expiry, storage | Delete proxy credential | | `kimi` | Device code | Unsupported | User, expiry, scope, storage | Delete proxy credential | | `grok` | Browser PKCE | Device code | Expiry and storage | Delete proxy credential | | `cursor` | Browser polling flow | Unsupported | Source, claims, expiry | Delete proxy credential | Examples: ```sh claude-code-proxy codex auth login claude-code-proxy grok auth device claude-code-proxy kimi auth status claude-code-proxy cursor auth logout ``` A missing credential makes `auth status` exit with status 1. Other provider command failures exit with status 2. Successful commands exit with status 0. Logout removes the local proxy-owned credential. It does not call the provider to revoke a refresh token. ## Development commands [Section titled “Development commands”](#development-commands) From a source checkout: ```sh cargo run -- serve cargo test --all cargo fmt --all --check cargo clippy --all-targets -- -D warnings just check just docs ``` `just docs` installs the locked documentation dependencies and starts the Astro development server on an available local port. # Compatibility and limitations > Canonical security, account, protocol, model, context, multimodal, reasoning, tool, session, rate-limit, and deployment boundaries. claude-code-proxy targets Claude Code’s practical Anthropic API usage rather than complete protocol equivalence. ## Accounts and provider policy [Section titled “Accounts and provider policy”](#accounts-and-provider-policy) * Provider subscriptions, allowed models, regions, quotas, and enforcement remain under each provider’s control. * OpenAI has publicly welcomed using Codex through other coding harnesses, but public statements do not guarantee future policy or account treatment. * Kimi, Grok, and Cursor use unofficial client integrations. Review the terms and account risk for your use. * Upstream rate limits are shared with other clients on the same account. ## Listener security [Section titled “Listener security”](#listener-security) * Incoming clients are not authenticated. * The default bind address is `127.0.0.1`. * A non-loopback listener requires an external firewall or authenticating reverse proxy. * The proxy stores subscription credentials and can consume account quota, so an exposed listener is equivalent to exposing that capability. ## Anthropic API scope [Section titled “Anthropic API scope”](#anthropic-api-scope) * Messages supports streaming and non-streaming responses for the fields exercised by Claude Code. * `?beta=true` does not select a separate implementation. * Token counts are local estimates, not exact upstream tokenizer or billing counts. * Claude Code title generation and other structured background requests are forwarded and consume provider tokens. * Anthropic-specific fields without a provider mapping can be dropped. * Native OpenAI Responses passthrough is opt-in and limited to registered Codex models and response creation. ## Models and context [Section titled “Models and context”](#models-and-context) * Local registration does not guarantee account access to a model. * Unknown model IDs have no implicit provider fallback. * Anthropic-style aliases route only to the configured Codex or Kimi alias provider. * `[1m]` is a Claude Code client hint and does not change upstream context. * Provider context limits can be lower than Claude Code’s local threshold. * Switching provider or model can clear provider-specific continuation assumptions while Claude Code retains portable history. ## Codex [Section titled “Codex”](#codex) * Base64 user images and supported base64 tool-result images map to Responses images. Remote URLs and malformed or unsupported nested images remain text placeholders. * Reasoning summaries can appear as thinking blocks. Codex decides whether a summary is emitted. * Encrypted reasoning and compaction items remain provider continuation data and are not exposed as raw chain of thought. * Hosted web search supports mapped domain filters, but the Anthropic `max_uses` value is not enforced because Codex exposes no equivalent limit. * Strict JSON schema output is translated. Other Anthropic-only output settings can be omitted. * `previous_response_id` and server compaction state are in memory and require stable session routing. * Automatic transport fallback occurs only before an upstream request is sent, which avoids replaying possible side effects. ## Kimi [Section titled “Kimi”](#kimi) * The proxy exposes one Kimi Code wire model plus local aliases. * Reasoning effort supports Kimi’s low, medium, and high levels. * Images in tool results use Kimi tool-message image parts. * The persistent device ID is part of the login identity and must remain stable. ## Grok [Section titled “Grok”](#grok) * Model availability varies by account and region. * Hosted general web search and X search are translated with citations and usage. * The implemented multimodal path does not claim general image or video compatibility. ## Cursor Agent [Section titled “Cursor Agent”](#cursor-agent) * An installed Cursor Agent JavaScript bundle supplies protobuf classes. * The dynamic catalog reflects the installed Cursor Agent and can differ across machines. * The native tool bridge covers recognized `Read`, `Write`, and `Bash` calls when matching tools and a session ID are present. * Cursor workspace callbacks and arbitrary native tool forms do not have a general Claude tool bridge. * Conversation and pending tool state are in memory. Restarts clear them. * Cursor count-tokens uses a rough rendered-prompt estimate. ## Diagnostics and privacy [Section titled “Diagnostics and privacy”](#diagnostics-and-privacy) * Structured logs redact known credential keys, but user-provided strings can still contain secrets. * Error captures contain complete redacted failed responses. * Traffic captures intentionally preserve prompts and tool content. * Verbose logging and traffic capture should be scoped to a focused local investigation. For provider-specific behavior, use the [provider pages](/providers/choosing-a-provider/). For released changes, see the [Changelog](/reference/changelog/). # Configuration > Canonical claude-code-proxy configuration keys, environment variables, defaults, precedence, boolean parsing, and example config.json. Proxy settings come from environment variables or `config.json`. Precedence is **environment variable, config file, built-in default**. The `serve --port` option takes precedence over all port settings. These settings configure the proxy process. Claude Code client settings such as `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL`, and `CLAUDE_CODE_*` are documented separately in [Configure Claude Code](/using/configure-claude-code/). ## Example `config.json` [Section titled “Example config.json”](#example-configjson) ```json { "bindAddress": "127.0.0.1", "port": 18765, "aliasProvider": "codex", "codex": { "originator": "claude-code-proxy", "userAgent": "claude-code-proxy/0.1.24", "model": "gpt-5.6-sol", "effort": "high", "reasoningSummary": "auto", "serviceTier": "fast", "baseUrl": "https://chatgpt.com/backend-api/codex/responses", "transport": "websocket", "previousResponseId": false, "serverCompaction": false, "responsesApi": false }, "kimi": { "userAgent": "KimiCLI/1.37.0", "oauthHost": "https://auth.kimi.com", "baseUrl": "https://api.kimi.com/coding/v1" }, "grok": { "baseUrl": "https://cli-chat-proxy.grok.com/v1", "clientVersion": "0.2.93" }, "cursor": { "baseUrl": "https://api2.cursor.sh", "clientVersion": "0.48.5", "agentBundle": "/path/to/cursor-agent/index.js" }, "log": { "stderr": false, "verbose": false } } ``` All keys are optional. An unreadable file, malformed JSON, or incompatible field type causes the file configuration to be ignored and built-in or environment values to apply. ## Core and diagnostics [Section titled “Core and diagnostics”](#core-and-diagnostics) | Environment | Config key | Default | Purpose | | -------------------- | --------------- | ------------------------- | -------------------------------------------------------------------------------------- | | `CCP_BIND_ADDRESS` | `bindAddress` | `127.0.0.1` | Listener IP address. | | `PORT` | `port` | `18765` | Listener port. | | `CCP_CONFIG_DIR` | none | Platform config directory | Replaces the configuration and file-backed auth root. | | `CCP_ALIAS_PROVIDER` | `aliasProvider` | `codex` | Routes recognized Anthropic-style aliases through `codex` or `kimi`. | | `CCP_LOG_STDERR` | `log.stderr` | `false` | Mirrors logs to stderr when present in the environment, regardless of its value. | | `CCP_LOG_VERBOSE` | `log.verbose` | `false` | Preserves full string fields in structured logs when present, regardless of its value. | | `CCP_TRAFFIC_LOG` | none | `false` | Enables full request captures for `1`, `true`, or `yes`. | | `XDG_STATE_HOME` | none | `~/.local/state` | State base on macOS and Linux. | `CCP_CONFIG_DIR` affects `config.json` and file-backed provider auth. It does not relocate the state directory. ## Codex [Section titled “Codex”](#codex) | Environment | Config key | Default | Purpose | | -------------------------------- | -------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `CCP_CODEX_MODEL` | `codex.model` | unset | Forces every Codex request to one upstream model. | | `CCP_CODEX_EFFORT` | `codex.effort` | unset | Forces `none`, `low`, `medium`, `high`, `xhigh`, or `max`. | | `CCP_COMPACT_EFFORT` | none | `low` | Caps Codex reasoning effort for Claude Code summary compaction requests. `off` disables the cap and `none` removes reasoning. | | `CCP_CODEX_REASONING_SUMMARY` | `codex.reasoningSummary` | unset | Overrides summary mode. `off` and `none` suppress summaries. | | `CCP_CODEX_SERVICE_TIER` | `codex.serviceTier` | unset | Forces `fast` or `priority`, or `flex`. Fast is sent as `priority`. | | `CCP_CODEX_BASE_URL` | `codex.baseUrl` | ChatGPT Codex Responses URL | Changes the Codex endpoint. | | `CCP_CODEX_TRANSPORT` | `codex.transport` | `websocket` | Selects `websocket`, `http`, or `auto`. | | `CCP_CODEX_PREVIOUS_RESPONSE_ID` | `codex.previousResponseId` | `false` | Enables append-only WebSocket continuation for `1`, `true`, or `yes`. | | `CCP_CODEX_SERVER_COMPACTION` | `codex.serverCompaction` | `false` | Enables or disables native compaction for standard boolean words. | | `CCP_CODEX_RESPONSES_API` | `codex.responsesApi` | `false` | Enables `/v1/responses` for `1`, `true`, or `yes`. | | `CCP_CODEX_ORIGINATOR` | `codex.originator` | `claude-code-proxy` | Changes the Codex `originator` header. | | `CCP_CODEX_USER_AGENT` | `codex.userAgent` | `claude-code-proxy/` | Changes the Codex user-agent. | `CLAUDE_CODE_PROXY_CODEX_BASE_URL` remains an accepted fallback for the Codex base URL. `CCP_CODEX_BASE_URL` takes precedence. ## Kimi [Section titled “Kimi”](#kimi) | Environment | Config key | Default | Purpose | | --------------------- | ---------------- | -------------------------------- | ---------------------------- | | `CCP_KIMI_OAUTH_HOST` | `kimi.oauthHost` | `https://auth.kimi.com` | Changes the OAuth host. | | `CCP_KIMI_BASE_URL` | `kimi.baseUrl` | `https://api.kimi.com/coding/v1` | Changes the API base URL. | | `CCP_KIMI_USER_AGENT` | `kimi.userAgent` | `KimiCLI/1.37.0` | Changes the Kimi user-agent. | ## Grok [Section titled “Grok”](#grok) | Environment | Config key | Default | Purpose | | ------------------------- | -------------------- | ------------------------------------ | --------------------------------------- | | `CCP_GROK_BASE_URL` | `grok.baseUrl` | `https://cli-chat-proxy.grok.com/v1` | Changes the Responses API base URL. | | `CCP_GROK_CLIENT_VERSION` | `grok.clientVersion` | `0.2.93` | Changes the Grok client version header. | ## Cursor Agent [Section titled “Cursor Agent”](#cursor-agent) | Environment | Config key | Default | Purpose | | --------------------------- | ---------------------- | ------------------------ | --------------------------------------------------------------- | | `CCP_CURSOR_BASE_URL` | `cursor.baseUrl` | `https://api2.cursor.sh` | Changes the Cursor API base URL. | | `CCP_CURSOR_CLIENT_VERSION` | `cursor.clientVersion` | `0.48.5` | Changes Cursor client version headers. | | `CCP_CURSOR_AGENT_BUNDLE` | `cursor.agentBundle` | Auto-detected | Points to Cursor Agent’s bundled `index.js` protobuf schemas. | | `CCP_CURSOR_AUTH_TOKEN` | none | unset | Uses a bearer token instead of proxy-owned Cursor auth storage. | ## Shared compatibility fallbacks [Section titled “Shared compatibility fallbacks”](#shared-compatibility-fallbacks) `CCP_USER_AGENT` is the fallback when a Codex or Kimi provider-specific user-agent is absent. Prefer `CCP_CODEX_USER_AGENT` or `CCP_KIMI_USER_AGENT` in durable configuration. Endpoint and client identity overrides can break provider compatibility. Use defaults unless a controlled integration or focused diagnostic requires an override. # Files and storage > Canonical claude-code-proxy configuration, credential, device ID, log, error, traffic-capture, and service-log paths on macOS, Linux, and Windows. claude-code-proxy separates configuration and credentials from runtime state. ## Directory roots [Section titled “Directory roots”](#directory-roots) | Platform | Configuration root | State root | | -------- | ------------------------------------------------- | ----------------------------------------------------- | | macOS | `~/.config/claude-code-proxy` | `${XDG_STATE_HOME:-~/.local/state}/claude-code-proxy` | | Linux | `${XDG_CONFIG_HOME:-~/.config}/claude-code-proxy` | `${XDG_STATE_HOME:-~/.local/state}/claude-code-proxy` | | Windows | `%APPDATA%/claude-code-proxy` | `%LOCALAPPDATA%/claude-code-proxy` | Windows falls back to `%USERPROFILE%/AppData/Roaming` and `%USERPROFILE%/AppData/Local` when the corresponding environment variable is absent. `CCP_CONFIG_DIR` replaces the configuration root for the current process. It does not change the state root. ## Configuration [Section titled “Configuration”](#configuration) `config.json` lives directly under the configuration root. See [Configuration](/reference/configuration/) for its schema and precedence. ## Provider credentials [Section titled “Provider credentials”](#provider-credentials) On macOS, Codex and Cursor use Keychain services: * `claude-code-proxy.codex` * `claude-code-proxy.cursor` Kimi and Grok use `//auth.json` on every platform. Codex and Cursor use the same file layout on Linux and Windows. File-backed credentials are written with restrictive permissions where supported. When `CCP_CONFIG_DIR` is set, every provider uses `//auth.json`, including Codex and Cursor on macOS. `CCP_CURSOR_AUTH_TOKEN` bypasses Cursor’s local credential store for that process. The proxy owns these credentials independently of native Codex, Grok, and Cursor Agent stores. ## Kimi device ID [Section titled “Kimi device ID”](#kimi-device-id) Kimi stores a persistent UUID at `/kimi/device_id` for file-backed setups. It is bound into the Kimi token and must remain paired with that login. ## Structured log [Section titled “Structured log”](#structured-log) `proxy.log` lives under the state root. It uses JSON Lines and rotates at 20 MiB. Known credential keys, including authorization, access tokens, refresh tokens, ID tokens, and account headers, are redacted before writing. A Homebrew service also writes `service.log` under the state root. ## Failed responses [Section titled “Failed responses”](#failed-responses) `errors/` under the state root contains JSON files for failed proxy responses. A `request_failed` log event includes `errorFile`, which points to the complete redacted payload. Error payloads are safer to share than raw traffic captures, but inspect their prompt-derived content and paths before publishing them. ## Traffic captures [Section titled “Traffic captures”](#traffic-captures) Set `CCP_TRAFFIC_LOG=1` to create captures under `traffic/` in the state root. Requests are grouped by Claude Code session and request sequence. A request directory can include: * inbound Anthropic request and metadata * translated upstream request * upstream URL and redacted headers * raw or decoded upstream events * translated downstream events and response * transport or reducer error details Event filenames use monotonic sequence numbers so lexical order preserves emission order. **Traffic captures preserve content.** Header and token redaction does not remove prompts, source code, tool definitions, tool inputs, tool results, images, or provider output. Treat the entire directory as sensitive user data. Enable capture only for a focused reproduction, keep the directory local, and delete it after the investigation. # HTTP API > Canonical local HTTP routes for liveness, Anthropic Messages, token counting, model discovery, and optional native Codex Responses passthrough. The server speaks the subset of Anthropic and OpenAI protocols needed by Claude Code and the optional Codex native passthrough. **No client authentication.** The listener accepts requests without validating \`Authorization\` or \`x-api-key\`. Loopback is the default. Protect every non-loopback listener with a firewall or authenticating reverse proxy. ## `GET /healthz` [Section titled “GET /healthz”](#get-healthz) Liveness check: ```json {"ok":true} ``` It does not verify provider credentials or upstream availability. ## `POST /v1/messages` [Section titled “POST /v1/messages”](#post-v1messages) Accepts an Anthropic Messages request in streaming or non-streaming mode. `POST /v1/messages?beta=true` reaches the same route. The request `model` selects the provider. The proxy translates supported message content, system prompts, thinking settings, tool definitions, tool choice, tool calls, tool results, images, output configuration, metadata, and streaming behavior according to the provider. Streaming responses use Anthropic SSE events such as `message_start`, `content_block_start`, `content_block_delta`, `content_block_stop`, `message_delta`, and `message_stop`. Non-streaming requests are accumulated from the provider’s stream. Unknown models return HTTP 400 with the supported catalog. Missing provider auth returns HTTP 401. ## `POST /v1/messages/count_tokens` [Section titled “POST /v1/messages/count\_tokens”](#post-v1messagescount_tokens) Accepts the same basic Anthropic request shape and returns: ```json {"input_tokens":1234} ``` Codex, Kimi, and Grok use a local `gpt-tokenizer` estimate with `o200k_base`. Cursor estimates the rendered prompt from its character length. Counts support Claude Code compaction behavior and are estimates rather than provider billing values. ## `GET /v1/models` [Section titled “GET /v1/models”](#get-v1models) Returns Anthropic-shaped model discovery: ```json { "data": [ { "type": "model", "id": "gpt-5.6-sol", "display_name": "gpt-5.6-sol (codex)" } ], "has_more": false, "first_id": "gpt-5.6-sol", "last_id": "cursor:gpt-5.5" } ``` An optional `limit` query truncates `data` and sets `has_more`. The route does not expose a pagination cursor. Claude Code gateway discovery filters IDs according to its own model rules. See [Models and routing](/using/models-and-routing/). ## `POST /v1/responses` [Section titled “POST /v1/responses”](#post-v1responses) This route exists only when `CCP_CODEX_RESPONSES_API=1` or `codex.responsesApi` is true. It accepts a native OpenAI Responses request for a registered Codex model. The proxy: * validates the model against the Codex catalog * replaces incoming auth with proxy-owned ChatGPT Codex auth * refreshes rejected access tokens before forwarding a response * preserves native JSON responses and SSE bodies * records the request in the monitor and optional traffic capture It does not implement Images API, stored response retrieval or deletion, or WebSocket client ingress. ## Other routes [Section titled “Other routes”](#other-routes) Unmatched paths return the proxy’s not-found response. The server has no administrative mutation API, credential API, or remote shutdown route. # Configure Claude Code > Set Claude Code client variables for claude-code-proxy without mixing them with CCP proxy configuration. Claude Code reads its API connection when the process starts. These variables belong to **Claude Code**, not to the proxy server. ## Minimal client contract [Section titled “Minimal client contract”](#minimal-client-contract) ```sh ANTHROPIC_BASE_URL=http://127.0.0.1:18765 \ ANTHROPIC_AUTH_TOKEN=unused \ ANTHROPIC_MODEL=gpt-5.6-sol[1m] \ ANTHROPIC_SMALL_FAST_MODEL=gpt-5.6-luna[1m] \ CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \ CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 \ claude ``` | Claude Code variable | Purpose | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `ANTHROPIC_BASE_URL` | Sends Anthropic API requests to the local proxy. | | `ANTHROPIC_AUTH_TOKEN` | Satisfies Claude Code’s client credential requirement. The proxy does not use it for upstream auth. | | `ANTHROPIC_MODEL` | Selects the main request model and therefore the provider. | | `ANTHROPIC_SMALL_FAST_MODEL` | Selects the model for title generation, token-related background work, and other small requests. Use a model the proxy routes. | | `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` | Reduces background traffic sent to the subscription provider. | | `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1` | Prevents Claude Code from retrying a partially completed stream as non-streaming, which can duplicate tool calls. | The proxy always makes streaming upstream requests. It can still accumulate a non-streaming Anthropic response when the client requests one. ## Compaction settings [Section titled “Compaction settings”](#compaction-settings) A trailing `[1m]` tells Claude Code to use its larger local context policy. The proxy strips the suffix before upstream routing. It does not enlarge the provider’s context window. For Codex GPT-5.6 subscription models, set the threshold explicitly: ```sh CLAUDE_CODE_AUTO_COMPACT_WINDOW=272000 ``` For a provider and model with a different real context limit, choose a safe value or omit the override. `DISABLE_AUTO_COMPACT=1` disables automatic compaction while preserving manual `/compact`, but the session can then hit the upstream limit. ## Persistent Claude Code settings [Section titled “Persistent Claude Code settings”](#persistent-claude-code-settings) If every Claude Code session should use the proxy, put client variables in `~/.claude/settings.json`: ```json { "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:18765", "ANTHROPIC_AUTH_TOKEN": "unused", "ANTHROPIC_MODEL": "gpt-5.6-sol[1m]", "ANTHROPIC_SMALL_FAST_MODEL": "gpt-5.6-luna[1m]", "CLAUDE_CODE_AUTO_COMPACT_WINDOW": 272000, "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1, "CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK": 1 } } ``` Use process-level variables or a wrapper when you also launch Claude Code directly against Anthropic. See [Switching models and backends](/using/switching-models-and-backends/). ## Proxy settings are separate [Section titled “Proxy settings are separate”](#proxy-settings-are-separate) `CCP_*`, `PORT`, and `config.json` configure the **claude-code-proxy server process**. They control the listener, provider endpoints, transport, credentials, and diagnostics. They do not belong in Claude Code’s client environment unless the same shell also starts the proxy. See [Configuration](/reference/configuration/) for the canonical server setting table. # For coding agents > Give coding agents machine-readable docs, model discovery, the minimal environment contract, authoritative references, diagnostics, and safe data-handling rules. This site publishes machine-readable documentation for coding agents alongside the human pages. ## Machine-readable docs [Section titled “Machine-readable docs”](#machine-readable-docs) * [`/llms.txt`](/llms.txt) is the compact index and is linked in the site header. * [`/llms-full.txt`](/llms-full.txt) contains the assembled documentation body for retrieval when the index is not enough. Start with `llms.txt`, follow only the pages relevant to the task, and prefer canonical reference pages over copied command tables in prompts or project notes. ## Discover models at runtime [Section titled “Discover models at runtime”](#discover-models-at-runtime) The installed CLI and running server are authoritative for the active build: ```sh claude-code-proxy models claude-code-proxy models --full curl -s http://127.0.0.1:18765/v1/models ``` Use the compact CLI output for a provider overview. Use `--full` when a Cursor model alias must be resolved. Do not maintain an exhaustive model list in agent memory because provider catalogs and account access change. ## Minimal environment contract [Section titled “Minimal environment contract”](#minimal-environment-contract) To launch Claude Code through a running local proxy, set: ```sh ANTHROPIC_BASE_URL=http://127.0.0.1:18765 ANTHROPIC_AUTH_TOKEN=unused ANTHROPIC_MODEL= ANTHROPIC_SMALL_FAST_MODEL= CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 ``` `ANTHROPIC_*` and `CLAUDE_CODE_*` configure the Claude Code client. `CCP_*`, `PORT`, and `config.json` configure the proxy process. Keep those layers separate when editing settings or debugging a launch. ## Authoritative references [Section titled “Authoritative references”](#authoritative-references) Use these pages for exact operational details: * [Command reference](/reference/command-reference/) for CLI syntax and exit behavior * [Configuration](/reference/configuration/) for keys, environment variables, precedence, and defaults * [Files and storage](/reference/files-and-storage/) for credential, log, error, and traffic paths * [HTTP API](/reference/http-api/) for local route contracts * [Compatibility and limitations](/reference/compatibility-and-limitations/) for translation boundaries * [Changelog](/reference/changelog/) for released behavior For a source checkout, implementation and tests are the final authority when documentation and behavior disagree. Relevant surfaces include `src/main.rs`, `src/config.rs`, `src/registry.rs`, `src/server.rs`, `src/paths.rs`, `src/providers/`, and integration tests under `tests/`. ## Diagnostics workflow [Section titled “Diagnostics workflow”](#diagnostics-workflow) 1. Check liveness with `curl http://127.0.0.1:18765/healthz`. 2. Check the selected model with `claude-code-proxy models`. 3. Check provider credentials with ` auth status`. 4. Read the monitor request detail and structured `proxy.log`. 5. Read the redacted payload under `errors/` for a failed response. 6. Enable verbose logging or traffic capture only for a focused reproduction. A source checkout includes `./scripts/debug-proxy`, which starts an isolated proxy on a random loopback port and prints every artifact path. ## Handle sensitive data safely [Section titled “Handle sensitive data safely”](#handle-sensitive-data-safely) **Prompts and traffic captures are sensitive.** Traffic captures preserve inbound prompts, tool definitions, tool inputs, tool outputs, translated requests, and stream events. Redacted headers do not make that content safe to publish. * Never print, commit, upload, or paste provider credentials, refresh tokens, session cookies, or account identifiers. * Treat Claude prompts, source excerpts, tool output, file paths, and traffic captures as user data. * Share the smallest redacted error payload that explains the failure. * Ask before sending diagnostics to an external service. * Keep traffic capture disabled outside a focused debugging session. * Delete sensitive temporary captures after the investigation. * Do not bind the unauthenticated listener beyond loopback without an access control layer. Structured logs redact known credential fields, but verbose values and prompts can still contain secrets supplied by the user or tools. Inspect before sharing. # Models and routing > Understand provider model patterns, aliases, Codex fast mode, context hints, small models, model listing, and Claude Code gateway discovery. The model ID in each request selects its provider. One proxy listener can serve every provider. ## Routing patterns [Section titled “Routing patterns”](#routing-patterns) | Pattern | Provider | | ----------------------------------------------------------------------------------------------------- | ------------------------------------- | | Registered `gpt-*` IDs and their `-fast` forms | Codex | | `kimi-for-coding`, `kimi-k2.6`, `k2.6` | Kimi | | `grok-composer-2.5-fast`, `grok-4.5` | Grok | | `cursor`, Cursor legacy aliases, `cursor:`, `cursor-plan:`, `cursor-ask:` | Cursor Agent | | Anthropic-style aliases such as `haiku`, `sonnet`, `opus`, `fable`, and registered `claude-*` aliases | The `aliasProvider`, Codex by default | An unknown ID returns HTTP 400 with the supported provider catalog. There is no implicit fallback for arbitrary model names. ## Prefer the live catalog [Section titled “Prefer the live catalog”](#prefer-the-live-catalog) The model list changes faster than documentation. Ask the installed CLI: ```sh claude-code-proxy models claude-code-proxy models --full ``` The compact command abbreviates Cursor’s dynamic aliases. `--full` prints every alias discovered through the installed Cursor Agent catalog. The HTTP equivalent is: ```sh curl http://127.0.0.1:18765/v1/models ``` ## Codex fast mode [Section titled “Codex fast mode”](#codex-fast-mode) Every registered Codex model also has a local `-fast` form. The proxy removes `-fast` from the upstream model and requests the priority service tier. A configured `codex.serviceTier` or `CCP_CODEX_SERVICE_TIER` override wins. ## The `[1m]` hint [Section titled “The \[1m\] hint”](#the-1m-hint) A trailing `[1m]` affects Claude Code’s local compaction policy. The proxy strips it before matching and forwarding the model. Use it only when the upstream model and account can accept the resulting context, and set a safe `CLAUDE_CODE_AUTO_COMPACT_WINDOW` when the real limit is below one million tokens. ## Main and small models [Section titled “Main and small models”](#main-and-small-models) Set both model variables to routable IDs: ```sh ANTHROPIC_MODEL=gpt-5.6-sol[1m] ANTHROPIC_SMALL_FAST_MODEL=gpt-5.6-luna[1m] ``` Claude Code sends background work to its small/fast model. Its built-in Haiku ID can route through `aliasProvider`, but a concrete provider ID keeps the behavior explicit. ## Claude Code `/model` [Section titled “Claude Code /model”](#claude-code-model) When `ANTHROPIC_BASE_URL` already points to the proxy, these can change the request model: * `claude --model ` at launch * Claude Code’s `/model` command in a session * `ANTHROPIC_MODEL` for a new process A model change can switch upstream providers because routing is per request. It does not change `ANTHROPIC_BASE_URL` or move the process back to direct Anthropic. ## Gateway model discovery [Section titled “Gateway model discovery”](#gateway-model-discovery) Enable Claude Code discovery at process start: ```sh CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 \ ANTHROPIC_BASE_URL=http://127.0.0.1:18765 \ ANTHROPIC_AUTH_TOKEN=unused \ ANTHROPIC_MODEL=gpt-5.6-sol[1m] \ ANTHROPIC_SMALL_FAST_MODEL=gpt-5.6-luna[1m] \ claude ``` `/v1/models` includes raw provider IDs and Anthropic-style aliases. Claude Code’s gateway picker filters for IDs beginning with `claude` or `anthropic`, so configured aliases are the entries most likely to appear. Raw IDs remain usable through `--model`, `/model`, and environment variables. ## Alias routing [Section titled “Alias routing”](#alias-routing) `CCP_ALIAS_PROVIDER=kimi` or `"aliasProvider": "kimi"` routes recognized Anthropic-style aliases to Kimi. Accepted values are `codex` and `kimi`. Explicit provider IDs always use their provider. # Monitor TUI > Use the claude-code-proxy monitor to inspect sessions, active and recent requests, providers, errors, token usage, throughput, and setup. `claude-code-proxy serve` opens the monitor when stdout is an interactive terminal. The same process runs the HTTP listener.  ## What the monitor shows [Section titled “What the monitor shows”](#what-the-monitor-shows) * Sessions grouped by Claude Code session ID and project * Active request lifecycle and selected provider or model * Recent requests, HTTP status, elapsed time, and errors * Input and output token totals * Output throughput based on matched upstream timing and cumulative usage samples * Paths to traffic captures when capture is enabled * Configuration overrides and a ready-to-copy Claude Code setup ## Keyboard controls [Section titled “Keyboard controls”](#keyboard-controls) | Key | Action | | ------------------ | ------------------------------- | | `Tab`, `←`, `→` | Change focused pane | | `j`, `k`, `↓`, `↑` | Move selection | | `Enter` | Open session or request details | | `Esc` | Close details or an overlay | | `?` | Toggle shortcut help | | `b` | Toggle the setup overlay | | `q` | Request a graceful shutdown | | `Ctrl-C` | Force shutdown | The request table changes columns as the terminal width changes. ## Plain logs [Section titled “Plain logs”](#plain-logs) Use plain output when the process runs under a service manager, in CI, or through a pipe: ```sh claude-code-proxy serve --no-monitor ``` Non-terminal stdout also selects plain mode. `CCP_LOG_STDERR=1` mirrors JSONL log events to stderr in plain mode. ## Demo mode [Section titled “Demo mode”](#demo-mode) Explore the full interface without binding a port or using provider credentials: ```sh claude-code-proxy demo ``` The deterministic simulation covers active, successful, and failed requests across providers, projects, throughput states, and responsive layouts. ## Background service [Section titled “Background service”](#background-service) A Homebrew installation can run at login: ```sh brew services start claude-code-proxy ``` Service output lives in `~/.local/state/claude-code-proxy/service.log` on macOS and Linux. The structured `proxy.log` shares the state directory. Provider login remains an interactive one-time command. # Switching models and backends > Choose launch-time patterns for switching between claude-code-proxy and direct Anthropic, then switch routed models within a proxy session. Claude Code binds its base URL and client auth when the process starts. A **backend switch** needs a new Claude Code process. A **model switch** can stay in the same proxy-backed session because the proxy routes each request by model ID. | Goal | Pattern | | ---------------------------------------------- | ---------------------------------------------------------- | | Always use the proxy | Put client variables in `~/.claude/settings.json` | | Try one model once | Prefix `claude` with environment variables or use an alias | | Toggle between proxy and direct Anthropic | Use a launch wrapper controlled by a flag | | Stay on the proxy and change provider or model | Use `/model`, `--model`, or a new `ANTHROPIC_MODEL` | ## One-shot aliases [Section titled “One-shot aliases”](#one-shot-aliases) ```sh alias csol='ANTHROPIC_BASE_URL=http://127.0.0.1:18765 ANTHROPIC_AUTH_TOKEN=unused ANTHROPIC_MODEL=gpt-5.6-sol[1m] ANTHROPIC_SMALL_FAST_MODEL=gpt-5.6-luna[1m] CLAUDE_CODE_AUTO_COMPACT_WINDOW=272000 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 claude' alias cgrok='ANTHROPIC_BASE_URL=http://127.0.0.1:18765 ANTHROPIC_AUTH_TOKEN=unused ANTHROPIC_MODEL=grok-4.5 ANTHROPIC_SMALL_FAST_MODEL=grok-4.5 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 claude' ``` These affect only the launched process. ## Flag-controlled wrapper [Section titled “Flag-controlled wrapper”](#flag-controlled-wrapper) Put a wrapper named `claude` ahead of the real binary on `PATH`. Set `REAL_CLAUDE` to a path that cannot resolve back to the wrapper. ```bash #!/usr/bin/env bash # Route Claude Code through the proxy when the flag file exists. set -euo pipefail real_claude="${REAL_CLAUDE:-$HOME/.local/bin/claude-real}" flag="$HOME/.claude/claude-code-proxy-enabled" model_file="$HOME/.claude/claude-code-proxy-model" if [ -f "$flag" ]; then model="gpt-5.6-sol[1m]" [ ! -f "$model_file" ] || model="$(tr -d '[:space:]' <"$model_file")" export ANTHROPIC_BASE_URL="http://127.0.0.1:18765" export ANTHROPIC_AUTH_TOKEN="unused" export ANTHROPIC_MODEL="${ANTHROPIC_MODEL:-$model}" export ANTHROPIC_SMALL_FAST_MODEL="${ANTHROPIC_SMALL_FAST_MODEL:-$model}" export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 export CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 fi exec "$real_claude" "$@" ``` Toggle it with ordinary file operations: ```sh mkdir -p ~/.claude touch ~/.claude/claude-code-proxy-enabled printf '%s\n' 'kimi-for-coding[1m]' > ~/.claude/claude-code-proxy-model # Disable for future sessions rm ~/.claude/claude-code-proxy-enabled ``` New processes read the flag and model. Running processes retain their launch environment. ## In-session model changes [Section titled “In-session model changes”](#in-session-model-changes) With the base URL already pointing to the proxy: ```text /model gpt-5.6-sol-fast[1m] /model kimi-for-coding[1m] /model grok-4.5 /model cursor:gpt-5.5 ``` The provider changes with the model. Provider auth must already exist. Claude Code preserves one conversation, while provider-specific in-memory continuation can reset when the provider or model changes. ## Scope [Section titled “Scope”](#scope) claude-code-proxy does not provide a profile GUI, rewrite Claude Code settings, change base URLs in a running process, or configure Desktop and IDE launch environments. Use process environment, a wrapper, or a dedicated profile manager for those concerns. # Troubleshooting > Diagnose listener, authentication, model routing, streaming, context, Cursor bundle, rate-limit, logging, and traffic-capture problems. ## Proxy is unreachable [Section titled “Proxy is unreachable”](#proxy-is-unreachable) Check the process and liveness route: ```sh curl http://127.0.0.1:18765/healthz ``` A healthy listener returns `{"ok":true}`. Confirm `ANTHROPIC_BASE_URL` uses the same address and port. `claude-code-proxy serve --port 11435` and `PORT=11435` change the listener port. `--port` wins for that command. ## Authentication error [Section titled “Authentication error”](#authentication-error) Check the provider selected by the model, then inspect its credential: ```sh claude-code-proxy codex auth status claude-code-proxy kimi auth status claude-code-proxy grok auth status claude-code-proxy cursor auth status ``` Use that provider’s login command when credentials are missing or expired. Codex requires ChatGPT subscription auth, not an OpenAI API key. Each provider uses proxy-owned credentials. ## Model returns HTTP 400 [Section titled “Model returns HTTP 400”](#model-returns-http-400) Run: ```sh claude-code-proxy models claude-code-proxy models --full ``` An unknown local ID returns a catalog in the error. A known ID can still be rejected upstream when the account, subscription, or region lacks access. Cursor’s prefixed form, such as `cursor:gpt-5.5`, forces Cursor routing and avoids cross-provider collisions. ## Background requests fail [Section titled “Background requests fail”](#background-requests-fail) Set `ANTHROPIC_SMALL_FAST_MODEL` to a concrete routable ID. Claude Code sends title and small background tasks through that model independently of the main model. ## A tool runs twice [Section titled “A tool runs twice”](#a-tool-runs-twice) Set `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1` for Claude Code. Retrying a partially completed stream as non-streaming can duplicate tool calls. ## Session reaches context limits [Section titled “Session reaches context limits”](#session-reaches-context-limits) `[1m]` changes Claude Code’s local compaction threshold and does not enlarge upstream context. Use a safe `CLAUDE_CODE_AUTO_COMPACT_WINDOW`, remove `[1m]`, or compact earlier. For ChatGPT GPT-5.6 subscription models, `272000` is the documented setup value. ## Codex WebSocket fails [Section titled “Codex WebSocket fails”](#codex-websocket-fails) Use HTTP SSE to isolate transport behavior: ```sh CCP_CODEX_TRANSPORT=http claude-code-proxy serve ``` `auto` falls back only when WebSocket setup fails before sending the request. It does not replay an in-flight request. ## Cursor bundle cannot be found [Section titled “Cursor bundle cannot be found”](#cursor-bundle-cannot-be-found) Cursor needs the installed Cursor Agent JavaScript bundle for protobuf schemas. Confirm Cursor Agent is installed, then set: ```sh CCP_CURSOR_AGENT_BUNDLE=/path/to/cursor-agent/index.js \ claude-code-proxy serve ``` ## Rate limited [Section titled “Rate limited”](#rate-limited) Upstream limits are shared with other clients on the same account. Codex limit responses and Kimi HTTP 429 responses surface as HTTP 429 with `retry-after`. Wait for the indicated interval or reduce concurrent traffic. ## Find the complete error [Section titled “Find the complete error”](#find-the-complete-error) The monitor shows request detail. `proxy.log` contains structured JSONL events, and `errors/` stores complete redacted failed-response payloads. A `request_failed` event includes the error file path. For a source checkout, run the isolated helper: ```sh ./scripts/debug-proxy ``` It prints a random local URL, a sourceable `client.env`, and artifact paths. Keep the terminal open, reproduce once, then press Ctrl-C. Captures contain sensitive prompt and tool content. ## Focused traffic capture [Section titled “Focused traffic capture”](#focused-traffic-capture) ```sh CCP_LOG_VERBOSE=1 \ CCP_TRAFFIC_LOG=1 \ claude-code-proxy serve --no-monitor ``` Traffic capture writes the inbound request, translated upstream request, upstream headers and events, and downstream events in emission order. Known credentials are redacted, but prompts and tool content are preserved. Disable capture and delete artifacts after diagnosis.