Skip to content

Use Claude Code with your ChatGPT, Kimi, Cursor or Grok subscription via a local Anthropic-compatible proxy

Rust

readme: document model and backend switching patterns

Raine Virta0aaa1a2e5349
diff --git a/README.md b/README.md
index 89b99da..a6410fb 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ Claude Code, powered by **OpenAI**, **Kimi**, **Grok**, or **Cursor**.
[Quick start](#quick-start) · [Providers](#providers) ·
[How it works](#how-it-works) · [Configuration](#configuration) ·
-[Limitations](#limitations)
+[Switching models](#switching-models-and-backends) · [Limitations](#limitations)
## Why?
@@ -180,7 +180,8 @@ accumulates a non-streaming Anthropic response for Claude Code. Disabling Claude
Code's streaming-to-non-streaming fallback avoids retrying a partially completed
stream in a way that can duplicate tool calls.
-Or set it persistently in `~/.claude/settings.json`:
+If the proxy is your everyday default and you rarely need native Anthropic in
+the same Claude config, put the env in `~/.claude/settings.json`:
```json
{
@@ -196,6 +197,10 @@ Or set it persistently in `~/.claude/settings.json`:
}
```
+If you switch backends often, leave those proxy vars out of settings and use
+one of the process-start patterns in
+[Switching models and backends](#switching-models-and-backends).
+
### 5. Context window size
Claude Code decides auto-compaction based on the model's context window. For
@@ -219,60 +224,6 @@ If you'd rather disable auto-compact completely, set
`/compact` still works, but you risk hitting real upstream limits before
Claude Code can compact for you.
-## Toggling between proxy and direct Anthropic
-
-If you still have an Anthropic subscription you want to fall back to, you can
-put a small wrapper in front of `claude` that only injects the proxy env vars
-when a flag file exists, plus a toggle script to flip the flag. Leave
-`~/.claude/settings.json` free of proxy env vars so direct-to-Anthropic remains
-the default.
-
-`~/.local/bin/claude` (ahead of the real `claude` on `PATH`):
-
-```bash
-#!/bin/bash
-# Wrapper that optionally routes to claude-code-proxy.
-# Active when ~/.claude/claude-code-proxy-enabled exists.
-
-if [ -f "$HOME/.claude/claude-code-proxy-enabled" ]; then
- export ANTHROPIC_BASE_URL="http://localhost:18765"
- export ANTHROPIC_AUTH_TOKEN="unused"
- export ANTHROPIC_MODEL="gpt-5.6-sol[1m]"
- export ANTHROPIC_SMALL_FAST_MODEL="gpt-5.6-luna[1m]"
- export CLAUDE_CODE_AUTO_COMPACT_WINDOW="372000"
- export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"
- export CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK="1"
-fi
-
-exec "$HOME/.local/bin/claude" "$@"
-```
-
-Adjust the exec path if the real `claude` binary lives elsewhere on your
-system (e.g. `$(bun pm bin -g)/claude`, `$HOME/.claude/local/claude`).
-
-`claude-proxy-toggle` (anywhere on your `PATH`):
-
-```bash
-#!/bin/bash
-# Toggle claude-code-proxy routing for the claude wrapper.
-set -euo pipefail
-
-flag="$HOME/.claude/claude-code-proxy-enabled"
-
-if [ -f "$flag" ]; then
- rm "$flag"
- echo "proxy: off"
-else
- mkdir -p "$(dirname "$flag")"
- touch "$flag"
- echo "proxy: on"
-fi
-```
-
-Run `claude-proxy-toggle` to flip between routing through the proxy (Codex /
-Kimi) and talking to Anthropic directly. New or continued `claude` sessions pick up
-the change immediately; existing sessions keep whatever they started with.
-
## Providers
### Codex (ChatGPT)
@@ -797,6 +748,210 @@ CCP_TRAFFIC_LOG=1`.
that directory, including on macOS.
`CCP_CURSOR_AUTH_TOKEN` overrides local proxy-owned storage.
+## Switching models and backends
+
+Claude Code binds the API base URL and auth when the process starts. Switching
+**backends** (proxy vs direct Anthropic, or a different Anthropic-compatible
+host) is a launch-time concern. Switching **models while already pointed at
+this proxy** can often stay in-session, because the proxy routes each request
+by model id.
+
+This project does not ship a universal profile manager. Use process env, a
+tiny shell wrapper, or Claude Code's own `/model` when the base URL already
+points here.
+
+### Choose a pattern
+
+| Goal | Pattern |
+| --- | --- |
+| Always use the proxy | Put proxy env in `~/.claude/settings.json` (see [Quick start](#4-point-claude-code-at-it)) |
+| Try one model once | Prefix `claude` with env vars, or use a shell alias |
+| Flip proxy on/off without editing JSON | Flag-file wrapper + toggle script |
+| Stay on the proxy, change model | `/model`, `--model`, or change `ANTHROPIC_MODEL` for new sessions |
+
+### One-shot launch and aliases
+
+Any of the `ANTHROPIC_BASE_URL=... claude` examples in
+[Quick start](#4-point-claude-code-at-it) are one-shots: they do not rewrite
+settings. Shell aliases are enough for daily muscle memory:
+
+```sh
+alias csol='ANTHROPIC_BASE_URL=http://localhost: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=372000 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 claude'
+alias cgrok='ANTHROPIC_BASE_URL=http://localhost: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'
+```
+
+### Sticky proxy on/off (recommended multi-backend setup)
+
+If you still use an Anthropic subscription sometimes, leave proxy env out of
+`~/.claude/settings.json` and inject it only when a flag file exists. Put a
+wrapper ahead of the real `claude` on `PATH`, and point `exec` at the real
+binary (not back at the wrapper).
+
+Example wrapper:
+
+```bash
+#!/usr/bin/env bash
+# Optionally route Claude Code through claude-code-proxy.
+# Active when ~/.claude/claude-code-proxy-enabled exists.
+set -euo pipefail
+
+# Path to the real Claude Code binary. Do not point this at this script.
+real_claude="${REAL_CLAUDE:-$HOME/.local/bin/claude}"
+
+if [ -f "$HOME/.claude/claude-code-proxy-enabled" ]; then
+ model_file="$HOME/.claude/claude-code-proxy-model"
+ main_model="gpt-5.6-sol[1m]"
+ small_model="gpt-5.6-luna[1m]"
+
+ if [ -f "$model_file" ]; then
+ main_model="$(tr -d '[:space:]' <"$model_file")"
+ case "$main_model" in
+ gpt-5.6-sol|gpt-5.6-sol\[1m\])
+ main_model="gpt-5.6-sol[1m]"
+ small_model="gpt-5.6-luna[1m]"
+ ;;
+ gpt-5.5|gpt-5.5\[1m\])
+ main_model="gpt-5.5[1m]"
+ small_model="gpt-5.4-mini[1m]"
+ ;;
+ kimi|kimi-for-coding|kimi-for-coding\[1m\])
+ main_model="kimi-for-coding[1m]"
+ small_model="kimi-for-coding[1m]"
+ ;;
+ grok|grok-4.5)
+ main_model="grok-4.5"
+ small_model="grok-4.5"
+ ;;
+ composer|composer-2.5-fast)
+ main_model="composer-2.5-fast"
+ small_model="composer-2.5-fast"
+ ;;
+ *)
+ small_model="$main_model"
+ ;;
+ esac
+ fi
+
+ export ANTHROPIC_BASE_URL="http://localhost:18765"
+ export ANTHROPIC_AUTH_TOKEN="unused"
+ export ANTHROPIC_MODEL="${ANTHROPIC_MODEL:-$main_model}"
+ export ANTHROPIC_SMALL_FAST_MODEL="${ANTHROPIC_SMALL_FAST_MODEL:-$small_model}"
+ export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
+ export CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1
+
+ case "$main_model" in
+ gpt-5.6-sol\[1m\]|gpt-5.6-luna\[1m\]|gpt-5.6-terra\[1m\])
+ export CLAUDE_CODE_AUTO_COMPACT_WINDOW="${CLAUDE_CODE_AUTO_COMPACT_WINDOW:-372000}"
+ ;;
+ esac
+fi
+
+exec "$real_claude" "$@"
+```
+
+If the wrapper itself is installed as `~/.local/bin/claude`, set
+`REAL_CLAUDE` to the underlying binary under
+`~/.local/share/claude/versions/` (or another path that is not this script).
+
+Toggle script (`claude-proxy-toggle` on your `PATH`):
+
+```bash
+#!/usr/bin/env bash
+# Toggle claude-code-proxy routing for the Claude wrapper.
+set -euo pipefail
+
+flag="$HOME/.claude/claude-code-proxy-enabled"
+
+if [ -f "$flag" ]; then
+ rm "$flag"
+ echo "proxy: off"
+else
+ mkdir -p "$(dirname "$flag")"
+ touch "$flag"
+ echo "proxy: on"
+fi
+```
+
+Optional sticky default proxy model:
+
+```bash
+#!/usr/bin/env bash
+# Usage: claude-proxy-model [model-id]
+# With no args, print the current sticky proxy model.
+set -euo pipefail
+
+model_file="$HOME/.claude/claude-code-proxy-model"
+default_model="gpt-5.6-sol[1m]"
+
+if [ "${1:-}" = "" ]; then
+ if [ -f "$model_file" ]; then
+ tr -d '[:space:]' <"$model_file"
+ printf '\n'
+ else
+ printf '%s\n' "$default_model"
+ fi
+ exit 0
+fi
+
+mkdir -p "$(dirname "$model_file")"
+printf '%s\n' "$1" >"$model_file"
+echo "proxy model: $1"
+```
+
+Examples:
+
+```sh
+claude-proxy-toggle # proxy on/off for new sessions
+claude-proxy-model grok-4.5 # sticky default while proxy is on
+claude-proxy-model gpt-5.6-sol[1m]
+ANTHROPIC_MODEL=kimi-for-coding[1m] claude # one-shot override
+```
+
+New Claude sessions pick up flag/model changes. A session that is already
+running keeps the env it started with.
+
+### Switch models while staying on the proxy
+
+While `ANTHROPIC_BASE_URL` already points at this proxy, Claude Code can change
+the request model without a new backend:
+
+- start a session with a different `ANTHROPIC_MODEL`
+- pass `claude --model <id>`
+- use Claude Code's `/model` command in-session
+
+The proxy chooses the upstream provider from the model id on each request, so
+`gpt-5.6-sol`, `kimi-for-coding`, `grok-4.5`, and `cursor:...` can share one
+`serve` process.
+
+To populate Claude Code's model picker from the proxy's `/v1/models` catalog,
+enable gateway discovery when launching:
+
+```sh
+CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 \
+ANTHROPIC_BASE_URL=http://localhost: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
+```
+
+`/model` only changes the model id. It does not move a session from the proxy
+to direct Anthropic or the other way around. For that, start a new process with
+different env (or flip the flag-file wrapper and open a new session).
+
+### What this project does not manage
+
+- multi-provider profile GUIs or account managers
+- rewriting `~/.claude/settings.json` for each switch
+- mid-session base URL / auth changes
+- IDE or Desktop launch wiring outside process env
+
+If you need a cross-app profile switcher, use a dedicated tool for that. For
+Claude Code + this proxy, process-start env plus `/model` on the proxy is the
+supported shape.
+
## Limitations
- **Terms of service:** OpenAI has [publicly welcomed using Codex through other