Why

One Claude Max subscription is one rate limit. If you spend your day in Claude Code you
know the shape of it: a long session, a wall of 429, and a cooldown you have to sit out.
Current Claude Code builds no longer retry rate limits themselves, so it surfaces as an
error mid-conversation.

CC-Router is a local proxy that sits between your tooling and the providers. It spreads
sessions across every subscription you own and fails a rate-limited request over to
another account before a single response byte reaches the client.

1 account   →  hit the limit, the session errors out
3 accounts  →  sessions spread across all three; a 429 fails over mid-flight

The part that makes it usable day to day: each conversation stays pinned to one
account. A Claude Code turn resends its whole prior context, and Anthropic caches that
prefix per account — scatter the turns and you re-pay for the cache every time. CC-Router
distributes new sessions instead of individual requests, so your cache stays warm.

Everything else is unchanged. Same claude, same codex, same streaming, extended
thinking, tool use and prompt caching — passed through byte for byte.

Features

• Cache-aware session routing — pins each session to one account, spreads new sessions across 2–20 accounts (details)
• Automatic failover & retry — a 429 moves to another account, a 5xx is retried in-router, always before the first response byte
• Multi-provider routing — model prefixes send claude/* to Claude subscriptions and openai/* / gpt-* to ChatGPT/Codex (details)
• Model-aware rate limits — skips accounts whose global or per-model allowance is spent, and respects scoped cooldowns
• Automatic token refresh — OAuth tokens refresh before expiry and are written atomically (details)
• Live dashboard — terminal UI for account health, usage windows, live activity, and routing toggles (details)
• Grok CLI overview — your Grok/xAI subscription's plan and session state in the same dashboard, alongside the accounts that are routed (details)
• Guided setup — cc-router setup pulls tokens from the Keychain or credentials file and wires up your clients
• Client mode — point another device you own at your private router (details)
• Flexible deployment — background daemon, native auto-start (launchd/systemd), foreground, or Docker Compose (details)
• Locked down by default — tokens stay on your machine, proxy auth is required on non-loopback binds (details)

Supported platforms and harnesses

Routed — requests are proxied to these:

Monitored — tracked and shown in the dashboard, not proxied:

Harnesses

Quickstart

Requires Node.js 20 or 22 on macOS, Linux or Windows.

# 1. Install
npm install -g @timo972/cc-router

# 2. Extract tokens and configure your clients
cc-router setup

# 3. Start the proxy
cc-router start

# 4. Use Claude Code as usual — the proxy is transparent
claude

That's it. On first start you're asked how to run the router (background, foreground, or
auto-start on boot) and the choice is remembered; cc-router start --reconfigure changes
it later. Adding more accounts is cc-router accounts login, re-signing one in is
cc-router accounts reauth <id>, and cc-router status opens the dashboard.

Per-platform token extraction, Codex CLI, Docker and everything else lives in
the docs.

Usage history and API-equivalent cost

Run cc-router usage for persistent token history, provider/model stacked bars,
and a daily activity grid, each switchable between tokens and what the recorded
tokens would have cost at standard API rates, and narrowable to input or output.
Switch between day, week, month and year; history survives service restarts.
Monthly subscription costs can be recorded for comparison in the --json
report:

cc-router usage subscription set personal --monthly-usd 100 --from 2026-09-01
cc-router usage
cc-router usage --period month --provider claude --json

Use your actual monthly USD cost and account name in place of the example.
Missing prices or costs are explicitly marked incomplete. See the
usage reference for
configuration, keyboard controls, estimation limits and offline/remote access.

Documentation

Disclaimer

CC-Router uses the OAuth tokens of your own Claude Max and ChatGPT subscriptions.

Read Anthropic's and OpenAI's Terms of Service before using this tool. Using multiple
subscriptions to increase throughput may violate them. 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 account bans, loss of access, or any other
consequence of using this software. Use at your own risk.

Contributing

Bug reports and feature requests go to GitHub Issues.
For development setup, code conventions and the PR process, see CONTRIBUTING.md.

License

MIT

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 — please file issues here rather than upstream.
The original MIT copyright notice is retained in LICENSE.