Local multi-account router for Claude Max and OpenAI ChatGPT/Codex subscriptions.
Distribute Claude Code requests across Claude subscriptions, and expose an OpenAI Responses-compatible route for Codex CLI through the same proxy.
An actively maintained fork of VictorMinemu/CC-Router, published as
@timo972/cc-routerwith bug fixes and added features — most notably cache-aware sticky session routing, which pins each Claude Code session to one account so a conversation keeps hitting the same prompt cache instead of scattering its shared prefix across accounts. Also includes load-aware account leases, byte-transparent streaming fixes, and a round of security hardening. See CHANGELOG.md for the full list.
- Cache-aware session routing — keep each Claude Code session on one account while distributing new sessions across 2-20 Claude Max accounts
- Multi-provider routing — route
openai/*models to OpenAI ChatGPT/Codex subscription accounts and Claude models to Claude subscriptions - Transparent Claude proxy — Claude Code works normally; streaming, thinking, tool use, prompt caching all pass through
- Codex CLI support — configure Codex to use CC-Router as a Responses-compatible provider
- Automatic token refresh — OAuth tokens are refreshed before they expire, saved atomically to disk
- Model-aware rate limits — avoids accounts whose requested-model or global allowance is exhausted, and respects scoped cooldowns
- Client mode — connect another device you own to your private CC-Router (
cc-router client connect <url>) - Claude Desktop support — route Cowork / Agent-mode traffic through CC-Router via mitmproxy interception (macOS, Windows, Linux)
- Guided setup wizard — interactive
cc-router setupextracts tokens from Keychain or credentials file, configures everything - Live dashboard — real-time terminal UI showing account health, request counts, token usage, recent activity
- Proxy authentication — Bearer / x-api-key secret; required when binding a non-loopback interface
- Update notifications — new releases are announced in the CLI; installing is opt-in (
autoUpdate: true) - Multiple deployment modes — background daemon, native OS auto-start (launchd/systemd), foreground, Docker Compose
- Cross-platform — macOS, Linux, Windows; Node.js 20+
Warning
Read the disclaimer before using this tool.
Claude Code (terminal) ─┐
│ ANTHROPIC_BASE_URL=http://localhost:3456
│
Claude Desktop ─[mitmproxy]─┐ (optional — intercepts api.anthropic.com)
│
▼
┌─────────────────────────────────────┐
│ CC-Router :3456 │
│ │
│ 1. Receives /v1/messages or │
│ /v1/responses │
│ 2. Parses model provider prefix │
│ 3. Picks a Claude or OpenAI account│
│ 4. Refreshes token if expiring │
│ 5. Injects Authorization: Bearer │
│ 6. Forwards to Anthropic, OpenAI │
│ Codex backend, or LiteLLM │
└──────────────┬──────────────────────┘
│
▼
api.anthropic.com
(authenticated with
OAuth token of account N)
All standard Claude Code features work transparently on the Claude route: streaming, extended thinking, tool use, prompt caching. OpenAI subscription routing is available for Codex-compatible Responses requests and Claude Code cross-routing with the limitations documented below.
CC-Router keeps requests from one Claude Code session on the same eligible Anthropic subscription account. This session affinity remains account-based and preserves prompt-cache locality instead of scattering a conversation's shared prefix across account-specific caches. The model requested by each Messages call affects whether the bound account is still eligible; changing models does not create a second binding, but it can make the existing binding fail over when that account cannot serve the new model. New sessions prefer the account with the fewest in-flight requests, then the fewest bound sessions, then included allowance over paid extra usage, then the most applicable global and requested-model headroom; exact ties use a rotating round-robin order.
Anthropic cooldowns, effective global or requested-model quota exhaustion, disabled accounts, invalid authentication, and unhealthy accounts are hard exclusions. The configured per-account percentage caps are softer policy controls: when at least one account is otherwise usable but every usable account is over a configured cap, CC-Router may explicitly fall back to the least-loaded capped account. It never uses that fallback to bypass an Anthropic cooldown or exhausted effective quota.
If an upstream account returns 401, 429, or 529, CC-Router passes that response through unchanged and invalidates the session's affinity. The client's next retry can then select another usable account; the router never retries after response bytes have started. If no account is usable before forwarding begins, the router instead returns a local Anthropic-shaped 429 whenever any account is blocked by a rate limit or exhausted quota. That 429 includes Retry-After only when a trustworthy unblock time is known. A local 503 is reserved for entirely non-rate-limit unavailability, such as all accounts being disabled or unhealthy. Either local response makes no Anthropic Messages request. Affinity mappings exist only in process memory, expire after one hour of inactivity, and are capped in size. Session IDs are never persisted or logged.
Streaming remains byte-transparent. In particular, CC-Router never appends a synthetic message_stop event. proxyRequestTimeoutMs protects only the phase before Anthropic response headers arrive; once a response starts, its body continues through the native byte-exact proxy pipe. Automatic cc-router configure setup manages Claude Code's event-level and byte-level stream idle watchdogs at 30 minutes. Restart any existing Claude Code process after configuration so it inherits those values.
Claude Desktop support is opt-in and requires a small interceptor (mitmproxy) because Claude Desktop doesn't expose a custom API endpoint setting. See Claude Desktop support.
Claude Max has rate limits per account. If you hit them regularly mid-session — waiting for cooldowns, getting 429s — you're a good candidate.
With two accounts you double your effective rate limit. With three, you triple it. The proxy distributes requests automatically; you don't change how you use Claude Code at all.
1 account → hit limit, wait 60s, continue
3 accounts → new sessions spread across all three; each session stays cache-local
# 1. Install
npm install -g @timo972/cc-router
# 2. Wizard: extract tokens + configure Claude Code automatically
cc-router setup
# 3. Start the proxy
cc-router start
# 4. Use Claude Code normally — the proxy is transparent
claudeThat's it. Claude Code will route through the proxy without any further changes.
On first run, cc-router start asks how you want to run (background/foreground, auto-start on boot, server mode) and remembers your choice. Next time, it just starts. To change preferences later:
cc-router start --reconfigureRequirements: Node.js 20 or 22.
npm install -g @timo972/cc-routerVerify:
cc-router --versioncc-router can extract OAuth tokens directly from the macOS Keychain — no manual copy-pasting needed.
cc-router setup
# Select "Extract automatically from macOS Keychain"For multiple accounts, you need to switch accounts in Claude Code between extractions:
# Account 1 is already logged in — run setup and extract
cc-router setup
# To add account 2:
claude logout && claude login # log in with account 2
cc-router setup --add # extract and merge
claude logout && claude login # log back in with account 1Tokens are read from ~/.claude/.credentials.json:
cc-router setup
# Select "Read from ~/.claude/.credentials.json"Make sure Claude Code is installed and you have run claude login at least once.
Same as Linux — tokens are read from ~/.claude/.credentials.json (Windows path: %USERPROFILE%\.claude\.credentials.json).
cc-router setupcc-router setup Interactive wizard: extract tokens + configure Claude Code
cc-router setup --add Add another account to an existing configuration
cc-router start Start proxy (asks preferences on first run, then remembers)
cc-router start --foreground Run in the foreground (stays in terminal)
cc-router start --reconfigure Re-ask run preferences (background/service/server mode)
cc-router start --litellm Start with LiteLLM in Docker (advanced mode)
cc-router stop Stop proxy (offers to remove auto-start / config)
cc-router stop --keep-config Stop proxy only (keep settings.json)
cc-router stop --full Stop + remove auto-start + revert Claude Code (no prompts)
cc-router revert Same as stop --full
cc-router status Live dashboard (updates every 2s, press q to quit)
cc-router status --json Print current stats as JSON and exit
cc-router models list List models discovered live from provider APIs
cc-router models list --json Print discovered models + routing as JSON
cc-router models set --claude-model anthropic/claude-sonnet-4-6
cc-router models set --openai-model openai/gpt-5-codex
cc-router logs View proxy logs (background mode)
cc-router logs -f Follow log output in real time
cc-router logs --lines 100 Show last 100 lines
cc-router accounts list List configured accounts (live stats if proxy is running)
cc-router accounts add Add an account interactively
cc-router accounts login-openai Sign in to OpenAI subscription auth with device code
cc-router accounts add-openai Add an OpenAI subscription account manually (experimental)
cc-router accounts remove <id> Remove a Claude or OpenAI account
cc-router configure (Re)write ~/.claude/settings.json
cc-router configure codex (Re)write ~/.codex/config.toml for Codex CLI
cc-router configure codex --model openai/gpt-5-codex
cc-router configure models --claude-model claude-sonnet-4-6 --openai-model gpt-5-codex
cc-router configure --show Show current Claude Code proxy settings
cc-router configure --remove Remove cc-router settings (same as revert without stopping)
cc-router client connect <url> Connect Claude Code to a remote CC-Router
cc-router client connect --desktop Also configure Claude Desktop interception
cc-router client disconnect Revert all client configuration
cc-router client status Show connection + remote server health
cc-router client start-desktop Start mitmproxy interceptor for Claude Desktop
cc-router client stop-desktop Stop mitmproxy interceptor
cc-router docker up Start full Docker stack (cc-router + LiteLLM)
cc-router docker up --build Rebuild cc-router image before starting
cc-router docker down Stop Docker containers
cc-router docker logs Tail all Docker logs
cc-router docker ps Show container status
cc-router docker restart [service] Restart a service
Claude Code → cc-router:3456 → api.anthropic.com
Best for personal use. No Docker required. Runs in the background by default, auto-starts on boot if you choose.
cc-router startClaude Code → cc-router:3456 → LiteLLM:4000 → api.anthropic.com
Adds a LiteLLM layer for usage logging, rate limiting, and a web dashboard at http://localhost:4000/ui.
cc-router docker up
# or: cc-router start --litellmSee docs/litellm-setup.md for details.
CC-Router exposes an OpenAI Responses-compatible endpoint for Codex CLI at /v1/responses. This lets Codex use OpenAI ChatGPT/Codex subscription accounts through the same local router that Claude Code uses for Claude subscriptions.
Configure Codex:
cc-router configure codex --model openai/gpt-5-codexThis writes a managed provider block to ~/.codex/config.toml:
model = "openai/gpt-5-codex"
model_provider = "cc-router"
[model_providers.cc-router]
name = "CC-Router"
base_url = "http://localhost:3456/v1"
wire_api = "responses"
env_key = "CC_ROUTER_TOKEN"Configure router-side model defaults and aliases:
cc-router configure models \
--claude-model claude-sonnet-4-6 \
--openai-model gpt-5-codexThis writes modelRouting to ~/.cc-router/config.json. It sets the Claude default, the OpenAI default, and practical aliases so claude/sonnet, sonnet, openai/default, and openai/codex resolve to the models you selected. Restart the router after changing these values.
Model discovery is dynamic. GET /v1/models returns an OpenAI-compatible model list by querying the configured Anthropic and OpenAI subscription APIs live:
curl http://localhost:3456/v1/modelsResults are provider-prefixed, for example anthropic/claude-sonnet-4-6 and openai/gpt-5-codex. Configured aliases such as openai/codex are added when their upstream model is available. If one provider is temporarily unavailable, CC-Router still returns the models discovered from the other providers.
Then run Codex with the proxy secret in CC_ROUTER_TOKEN when your router is password-protected:
CC_ROUTER_TOKEN=cc-rtr-your-secret codex -m openai/gpt-5.5Model prefixes:
| Prefix | Upstream |
|---|---|
openai/* |
OpenAI ChatGPT/Codex subscription route |
claude/* |
Claude subscription route |
anthropic/* |
Claude subscription route |
Examples after the configuration above:
| Public model | Routed upstream model |
|---|---|
openai/codex |
gpt-5-codex |
openai/default |
gpt-5-codex |
claude/sonnet |
claude-sonnet-4-6 |
Claude Code can also send a /v1/messages request with an openai/* model. CC-Router translates that Anthropic Messages request into an OpenAI Responses request and converts JSON or basic text SSE responses back into Anthropic-shaped message responses.
Current limitation: OpenAI-to-Anthropic streaming currently covers text deltas and final usage. Streaming tool-call normalization is still experimental.
OpenAI subscription account records are separated from Claude accounts with provider: "openai_subscription" so they do not enter the Anthropic token pool:
{
"id": "openai-primary",
"provider": "openai_subscription",
"accessToken": "eyJ...",
"refreshToken": "...",
"expiresAt": 1999999999000,
"scopes": ["openid", "profile", "email", "offline_access"]
}Recommended OpenAI subscription login:
cc-router accounts login-openaiThis uses the Codex device-code auth flow: the CLI prints a verification URL and one-time code, you approve the login in your browser, and CC-Router saves the resulting OpenAI subscription account record.
Manual account entry is also available for debugging:
cc-router accounts add-openaiThis prompts for the OpenAI access token, refresh token, expiry timestamp, and scopes, validates the record shape, and saves it without overwriting Claude accounts.
Client mode lets you connect another device you own to your private CC-Router over a trusted private network. It is not intended for sharing subscription accounts or proxy access with other people, or for exposing CC-Router to the public internet.
The setup wizard asks about this at the very first step:
cc-router setup
# → What do you want to do?
# • Host CC-Router on this machine
# • Connect to your existing CC-Router server ← pick thisOr use the dedicated command directly:
# Connect another device you own over your private network
cc-router client connect http://192.168.1.50:3456 --secret cc-rtr-abc123...
# Check status
cc-router client status
# Disconnect (restores Claude Code defaults)
cc-router client disconnectClient mode writes ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN into ~/.claude/settings.json, so Claude Code talks directly to the remote proxy. Nothing runs locally — no accounts, no proxy process, no resources.
cc-router client connect <url> Connect Claude Code to a CC-Router server
cc-router client connect --desktop Also configure Claude Desktop interception
cc-router client connect -s <secret> Pass the proxy secret inline (or use --secret)
cc-router client disconnect Revert all client configuration
cc-router client status Show current connection + remote server health
cc-router client start-desktop Start the Claude Desktop mitmproxy interceptor
cc-router client stop-desktop Stop the Claude Desktop interceptor
Claude Desktop (chat + Cowork) can be routed through CC-Router, but unlike Claude Code it does not respect ANTHROPIC_BASE_URL. It talks directly to api.anthropic.com via an embedded Anthropic SDK. To redirect its traffic, CC-Router uses mitmproxy in local redirect mode — a process-scoped interceptor that only captures Claude Desktop's network traffic and forwards it to the proxy.
This is opt-in — the setup wizard will ask if you want it.
- mitmproxy ≥ 10.1.5 (macOS, Windows) or ≥ 11.1 (Linux — requires kernel ≥ 6.8)
- Admin access to install the mitmproxy CA certificate
- On macOS: manual approval of mitmproxy's Network Extension (one time, via System Settings)
# macOS
brew install mitmproxy
# Windows
# Download the installer from https://mitmproxy.org/downloads/
# (or: pip install mitmproxy)
# Linux
pip install mitmproxy # kernel 6.8+ required for local modeDuring cc-router setup or cc-router client connect, answer Yes when asked about Claude Desktop. The wizard will:
- Check that mitmproxy is installed
- Generate the mitmproxy CA certificate (if not already present)
- Install the CA into the OS trust store (requires sudo/admin)
- Write the redirect addon to
~/.cc-router/interceptor/addon.py - On macOS, prompt you to approve the Network Extension
Then start the interceptor:
cc-router client start-desktopOpen Claude Desktop and send a message. The request will be intercepted and redirected to CC-Router. Requests carrying exactly one valid X-Claude-Code-Session-Id receive cache-aware sticky affinity; requests without one valid session header use load-aware unscoped routing and do not receive sticky affinity. Claude Desktop traffic normally follows the unscoped path.
cc-router client stop-desktop # Stop the interceptor (keep configuration)
cc-router client disconnect # Stop + remove all client configClaude Desktop
│
│ tries to connect to api.anthropic.com:443
▼
mitmproxy (local mode)
│ addon.py rewrites scheme/host to CC-Router
▼
CC-Router :3456 ──► api.anthropic.com (with OAuth Bearer token)
mitmproxy's local mode is process-scoped — it only intercepts traffic from the Claude process, not your browser, curl, or any other app. The OS-level interception uses:
| Platform | Mechanism |
|---|---|
| macOS | Network Extension (App Proxy Provider API) |
| Windows | WinDivert (WFP kernel driver) |
| Linux | eBPF (kernel ≥ 6.8) |
- macOS: "provider rejected new flow" — re-enable Mitmproxy Redirector in System Settings → General → Login Items & Extensions → Network Extensions, then restart mitmproxy.
- Windows: UAC prompt every start — expected; mitmproxy's redirector needs admin at runtime.
- Linux: "eBPF program failed to load" — check your kernel version with
uname -r. You need ≥ 6.8. - Chat shows "failed to connect" — make sure CC-Router is reachable from the mitmproxy process. Run
curl http://localhost:3456/cc-router/healthto verify the proxy is up.
To stop using cc-router and go back to normal Claude Code authentication:
cc-router revertThis stops the proxy process, removes the auto-start service (if installed), and removes cc-router's settings from ~/.claude/settings.json. Claude Code will use its own authentication on the next launch.
For a gentler approach, cc-router stop interactively asks what you want to clean up.
cc-router status CC-Router · standalone → api.anthropic.com · up 2h 14m · [q] quit
OPERATIONS base http://localhost:3456 · auth protected · models dynamic
Claude 2/2 healthy OpenAI 1/1 healthy · cross-route ready
endpoints /v1/messages /v1/responses /v1/models /cc-router/accounts
routing claude=claude-sonnet-4-6 aliases[sonnet] openai=gpt-5-codex aliases[codex]
models [m] list/select change [c] Claude [o] OpenAI
MODELS [m/r] refresh [↑/↓] select [c] Claude default [o] OpenAI default
current claude=claude-sonnet-4-6 openai=gpt-5-codex
▶ anthropic/claude-sonnet-4-6 Claude
openai/gpt-5-codex OpenAI
ACCOUNTS 2/2 healthy
● max-account-1 ok req 142 err 0 expires 6h 48m last 2s ago
● max-account-2 ok req 139 err 0 expires 6h 51m last 5s ago
TOTALS requests 281 · errors 0 · refreshes 2
RECENT ACTIVITY
14:23:01 → max-account-1 route
14:22:58 → max-account-2 route
14:22:45 ↻ max-account-1 refresh
Press q to quit. Run with --json for non-interactive output; the JSON includes an operational block with capabilities, endpoints, provider readiness, auth status, and model routing. Secrets and account tokens are never included.
The dashboard is also a control surface. In local mode it controls the local proxy; in client mode it controls the remote CC-Router configured by cc-router client connect. Authenticated account views include dynamic model-scoped allowance rows, their reset times, applicable global or requested-model cooldowns, paid-extra state, and whether the usage snapshot is fresh, stale, or unavailable. A stale row is shown as unknown rather than as authoritative available capacity.
| Key | Action |
|---|---|
Tab |
Switch focus between logs, accounts, and models |
n |
Add a Claude account |
e |
Enable/disable selected Claude account |
w / s |
Change selected Claude account weekly/session cap |
d |
Delete selected Claude account |
m / r |
Load or refresh discovered provider models |
c |
Set selected anthropic/* model as Claude default |
o |
Set selected openai/* model as OpenAI default |
List and change models without waiting for a package update:
cc-router models list
cc-router models set --claude-model anthropic/claude-sonnet-4-6
cc-router models set --openai-model openai/gpt-5-codexWhen the proxy is running, models set updates the live router and persists the new defaults. If the proxy is offline, it writes the configuration for the next start.
- Tokens are stored locally in
~/.cc-router/accounts.json, never in the repository - The file is excluded by
.gitignore - Writes are atomic (write to
.tmp, then rename) — no corruption on crash - Keychain reads use
execFilewith a fixed argument array — no shell injection - Anonymous opt-out telemetry via Aptabase (see Telemetry below)
See docs/security.md for details.
CC-Router sends a handful of anonymous lifecycle events to Aptabase (privacy-first, open source, EU-hosted). The goal is simple: know how many people use the project, which versions are live, and roughly how many instances are running — so we can prioritize fixes and features.
What we send — the entire payload lives in src/utils/telemetry.ts, audit it yourself:
| Event | When | Custom props |
|---|---|---|
app_started |
First proxy start after install | first_run: true |
setup_completed |
Setup wizard finishes successfully | account_count |
proxy_started |
Each cc-router start |
account_count, mode |
proxy_heartbeat |
Every hour while the proxy is running | uptime_minutes, account_count |
telemetry_disabled |
When you run cc-router telemetry off |
— |
Plus anonymous system props with every event: appVersion, osName (macOS/Linux/Windows), osVersion, locale, engineVersion (Node), and an anonymous installId (random UUID generated on first run, stored in ~/.cc-router/telemetry.json).
What we never send: IPs, OAuth tokens, account names, request content, prompts, responses, URLs, hostnames, usernames, file paths — nothing that could identify you or your usage patterns.
Disable it — three ways, any one works:
# 1. Persistent opt-out (recommended)
cc-router telemetry off
# 2. Respect the de-facto standard (honored by many OSS tools)
export DO_NOT_TRACK=1
# 3. Project-specific override
export CC_ROUTER_TELEMETRY=0Check status anytime: cc-router telemetry status.
CC-Router uses the OAuth tokens of your own Claude Max subscriptions.
Read Anthropic's Terms of Service before using this tool.
Using multiple Max subscriptions to increase throughput may violate the ToS. Anthropic has been known to ban accounts for unusual OAuth usage patterns. Do not share subscription accounts, OAuth credentials, or CC-Router proxy access with other people.The authors are not responsible for any account bans, loss of access, or other consequences resulting from the use of this software. Use at your own risk.
See CONTRIBUTING.md.
Bug reports → GitHub Issues
This project began as a fork of VictorMinemu/CC-Router
and is now maintained independently as @timo972/cc-router.
It is not affiliated with the upstream project, and issues should be filed here rather than upstream.
The original MIT copyright notice is retained in LICENSE.
