ai-cc-router 0.1.0

package/Dockerfile

@@ -0,0 +1,32 @@
+# ── Build stage ───────────────────────────────────────────────────────────────
+FROM node:22-alpine AS builder
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci
+
+COPY tsconfig.json ./
+COPY src/ ./src/
+RUN npm run build
+
+# ── Runtime stage ─────────────────────────────────────────────────────────────
+FROM node:22-alpine AS runtime
+WORKDIR /app
+
+ENV NODE_ENV=production
+# Port defaults — overridden by docker-compose environment section
+ENV PORT=3456
+ENV ACCOUNTS_PATH=/app/accounts.json
+
+# Install only production deps
+COPY package*.json ./
+RUN npm ci --omit=dev && npm cache clean --force
+
+COPY --from=builder /app/dist ./dist
+
+EXPOSE 3456
+
+# accounts.json is expected to be mounted at runtime via docker-compose volume
+# The container will exit with a clear error if it's not present
+ENTRYPOINT ["node", "dist/cli/index.js"]
+CMD ["start"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CC-Router Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,395 @@
+# CC-Router
+
+**Round-robin proxy for multiple Claude Max accounts.**  
+Distribute Claude Code requests across N subscriptions to multiply your throughput.
+
+[![CI](https://github.com/VictorMinemu/CC-Router/actions/workflows/ci.yml/badge.svg)](https://github.com/VictorMinemu/CC-Router/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/ai-cc-router)](https://www.npmjs.com/package/ai-cc-router)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+> **Warning**  
+> Read the [disclaimer](#disclaimer) before using this tool.
+
+---
+
+## How it works
+
+```
+Claude Code  (terminal)
+     │
+     │  ANTHROPIC_BASE_URL=http://localhost:3456
+     │  ANTHROPIC_AUTH_TOKEN=proxy-managed
+     ▼
+┌─────────────────────────────────────┐
+│  CC-Router  :3456                   │
+│                                     │
+│  1. Receives request  /v1/messages  │
+│  2. Round-robin → picks account N   │
+│  3. Refreshes token if expiring     │
+│  4. Injects  Authorization: Bearer  │
+│  5. Forwards to Anthropic (or       │
+│     LiteLLM for advanced mode)      │
+└──────────────┬──────────────────────┘
+               │
+               ▼
+        api.anthropic.com
+        (authenticated with
+         OAuth token of account N)
+```
+
+All standard Claude Code features work transparently: streaming, extended thinking, tool use, prompt caching.
+
+---
+
+## Use cases
+
+### Heavy user — one account isn't enough
+
+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.
+
+```text
+1 account  →  hit limit, wait 60s, continue
+3 accounts →  request rotates across all three, limit effectively tripled
+```
+
+---
+
+### Team sharing accounts — fewer subscriptions, same throughput
+
+A team of five doesn't need five Max subscriptions. In practice, developers don't all peak at the same time. Three accounts can comfortably serve five people working normal hours.
+
+#### Example setup: 5 devs, 3 accounts
+
+```text
+cc-router (hosted on a shared machine or VPS)
+     │
+     ├── max-account-1   ← alice's subscription
+     ├── max-account-2   ← bob's subscription
+     └── max-account-3   ← carol's subscription
+           │
+           └── serves: alice, bob, carol, dave, eve
+```
+
+Each developer sets their `ANTHROPIC_BASE_URL` to the shared proxy. Done. The proxy handles routing and token refresh invisibly.
+
+#### Cost example
+
+| Setup | Monthly cost |
+|-------|-------------|
+| 5 individual Max subscriptions | 5 × $100 = **$500/mo** |
+| 3 shared via cc-router | 3 × $100 = **$300/mo** |
+
+You save $200/mo without any loss in capability for a typical team workload.
+
+---
+
+### Hosting cc-router on a shared machine
+
+Run cc-router on a machine everyone on the team can reach — a home server, a VPS, or a spare machine on the office network.
+
+#### On the server
+
+```bash
+npm install -g cc-router
+cc-router setup          # configure the 3 shared accounts
+cc-router service install # auto-start on boot
+```
+
+By default cc-router binds to `localhost`. To accept connections from other machines, set the `HOST` environment variable:
+
+```bash
+# Listen on all interfaces (team LAN or VPS)
+HOST=0.0.0.0 cc-router start
+
+# Or configure it permanently in the service
+```
+
+#### On each developer's machine
+
+No installation needed. Just set two environment variables in `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://192.168.1.50:3456",
+    "ANTHROPIC_AUTH_TOKEN": "proxy-managed"
+  }
+}
+```
+
+Replace `192.168.1.50` with the server's IP or hostname. Then run `claude` normally.
+
+Or use the CLI to write the settings automatically:
+
+```bash
+cc-router configure --port 3456
+# Then manually update ANTHROPIC_BASE_URL to the remote IP
+```
+
+---
+
+### Hosting on a VPS (internet-accessible)
+
+If your team is distributed or works remotely, run cc-router on a VPS and expose it over HTTPS via a reverse proxy.
+
+#### Recommended nginx config
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name cc-router.yourcompany.com;
+
+    # ... SSL cert config (e.g. Let's Encrypt) ...
+
+    location / {
+        proxy_pass http://127.0.0.1:3456;
+        proxy_buffering off;          # required for SSE streaming
+        proxy_read_timeout 300s;      # required for long thinking requests
+        proxy_set_header X-Forwarded-For $remote_addr;
+    }
+}
+```
+
+Each developer then points to:
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "https://cc-router.yourcompany.com",
+    "ANTHROPIC_AUTH_TOKEN": "proxy-managed"
+  }
+}
+```
+
+**Security note:** if the proxy is internet-accessible, add authentication at the nginx level (basic auth, mTLS, or IP allowlist) so only your team can use it. cc-router does not implement user authentication itself.
+
+---
+
+## Quickstart
+
+```bash
+# 1. Install
+npm install -g 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
+claude
+```
+
+That's it. Claude Code will route through the proxy without any further changes.
+
+**Optional:** install as a system service so it starts automatically on boot:
+```bash
+cc-router service install
+```
+
+---
+
+## Installation
+
+**Requirements:** Node.js 20 or 22.
+
+```bash
+npm install -g ai-cc-router
+```
+
+Verify:
+```bash
+cc-router --version
+```
+
+---
+
+## Setup by platform
+
+### macOS
+
+cc-router can extract OAuth tokens directly from the macOS Keychain — no manual copy-pasting needed.
+
+```bash
+cc-router setup
+# Select "Extract automatically from macOS Keychain"
+```
+
+For multiple accounts, you need to switch accounts in Claude Code between extractions:
+```bash
+# 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 1
+```
+
+### Linux
+
+Tokens are read from `~/.claude/.credentials.json`:
+```bash
+cc-router setup
+# Select "Read from ~/.claude/.credentials.json"
+```
+
+Make sure Claude Code is installed and you have run `claude login` at least once.
+
+### Windows
+
+Same as Linux — tokens are read from `~/.claude/.credentials.json` (Windows path: `%USERPROFILE%\.claude\.credentials.json`).
+
+```bash
+cc-router setup
+```
+
+---
+
+## CLI Reference
+
+```text
+cc-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 on localhost:3456 (foreground)
+cc-router start --daemon     Start in background via PM2
+cc-router start --litellm    Start with LiteLLM in Docker (advanced mode)
+
+cc-router stop               Stop proxy + restore Claude Code to normal auth
+cc-router stop --keep-config Stop proxy only (keep settings.json)
+cc-router revert             Restore Claude Code to normal authentication
+
+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 accounts list      List configured accounts (live stats if proxy is running)
+cc-router accounts add       Add an account interactively
+cc-router accounts remove <id>  Remove an account
+
+cc-router service install    Register cc-router to start on system boot (PM2)
+cc-router service uninstall  Remove from system startup
+cc-router service status     Show PM2 service status
+cc-router service logs       Tail proxy logs from PM2
+
+cc-router configure          (Re)write ~/.claude/settings.json
+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 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
+```
+
+---
+
+## Modes of operation
+
+### Standalone (default — no Docker)
+
+```text
+Claude Code → cc-router:3456 → api.anthropic.com
+```
+
+Best for personal use. No Docker required.
+
+```bash
+cc-router start
+```
+
+### Full mode with LiteLLM (optional — requires Docker)
+
+```text
+Claude 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`.
+
+```bash
+cc-router docker up
+# or: cc-router start --litellm
+```
+
+See [docs/litellm-setup.md](docs/litellm-setup.md) for details.
+
+---
+
+## Reverting to normal Claude Code
+
+To stop using cc-router and go back to normal Claude Code authentication:
+
+```bash
+cc-router revert
+```
+
+This stops the proxy process and removes cc-router's settings from `~/.claude/settings.json`. Claude Code will use its own authentication on the next launch.
+
+---
+
+## Status dashboard
+
+```bash
+cc-router status
+```
+
+```text
+ CC-Router  ·  standalone → api.anthropic.com  ·  up 2h 14m  ·  [q] quit
+
+ 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.
+
+---
+
+## Security
+
+- 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 `execFile` with a fixed argument array — no shell injection
+- No telemetry, no external logging
+
+See [docs/security.md](docs/security.md) for details.
+
+---
+
+## Disclaimer
+
+> 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.
+>
+> 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.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Bug reports → [GitHub Issues](https://github.com/VictorMinemu/CC-Router/issues)
+
+---
+
+## License
+
+[MIT](LICENSE)

package/accounts.example.json

@@ -0,0 +1,16 @@
+[
+  {
+    "id": "max-account-1",
+    "accessToken": "sk-ant-oat01-REPLACE_ME",
+    "refreshToken": "sk-ant-ort01-REPLACE_ME",
+    "expiresAt": 1748658860000,
+    "scopes": ["user:inference", "user:profile"]
+  },
+  {
+    "id": "max-account-2",
+    "accessToken": "sk-ant-oat01-REPLACE_ME",
+    "refreshToken": "sk-ant-ort01-REPLACE_ME",
+    "expiresAt": 1748658860000,
+    "scopes": ["user:inference", "user:profile"]
+  }
+]

package/dist/cli/cmd-accounts.js

@@ -0,0 +1,142 @@
+import chalk from "chalk";
+import { loadAccounts, accountsFileExists, writeAccountsAtomic } from "../config/manager.js";
+import { saveAccounts } from "../proxy/token-refresher.js";
+import { formatExpiry, redactToken } from "../utils/token-extractor.js";
+import { PROXY_PORT } from "../config/paths.js";
+export function registerAccounts(program) {
+    const accounts = program
+        .command("accounts")
+        .description("Manage Claude Max accounts in the token pool");
+    // ── accounts list ────────────────────────────────────────────────────────
+    accounts
+        .command("list")
+        .description("List all configured accounts and their status")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        // Try to get live stats from the running proxy first
+        const liveStats = await fetchLiveStats();
+        if (!accountsFileExists()) {
+            console.log(chalk.yellow("No accounts configured. Run: cc-router setup"));
+            return;
+        }
+        const stored = loadAccounts();
+        if (stored.length === 0) {
+            console.log(chalk.yellow("accounts.json is empty. Run: cc-router setup"));
+            return;
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(liveStats ?? stored, null, 2));
+            return;
+        }
+        console.log(chalk.bold(`\n  Accounts (${stored.length} configured)\n`));
+        if (liveStats) {
+            console.log(chalk.green("  ● Proxy is running — showing live stats\n"));
+            for (const s of liveStats) {
+                const status = s.healthy
+                    ? chalk.green("✓ healthy")
+                    : chalk.red("✗ unhealthy");
+                const busy = s.busy ? chalk.yellow(" [busy]") : "";
+                const exp = s.expiresInMs > 0
+                    ? chalk.yellow(formatMs(s.expiresInMs))
+                    : chalk.red("EXPIRED");
+                console.log(`  ${chalk.bold(s.id.padEnd(24))}` +
+                    `  ${status}${busy}` +
+                    `  requests: ${chalk.cyan(String(s.requestCount).padStart(5))}` +
+                    `  errors: ${chalk.red(String(s.errorCount).padStart(3))}` +
+                    `  expires: ${exp}`);
+            }
+        }
+        else {
+            console.log(chalk.gray("  (Proxy not running — showing stored configuration)\n"));
+            for (const a of stored) {
+                const exp = formatExpiry(a.tokens.expiresAt);
+                const expColor = a.tokens.expiresAt > Date.now()
+                    ? chalk.yellow(exp)
+                    : chalk.red(exp);
+                console.log(`  ${chalk.bold(a.id.padEnd(24))}` +
+                    `  ${redactToken(a.tokens.accessToken).padEnd(26)}` +
+                    `  expires: ${expColor}` +
+                    `  scopes: ${chalk.gray(a.tokens.scopes.join(" "))}`);
+            }
+        }
+        console.log();
+    });
+    // ── accounts add ─────────────────────────────────────────────────────────
+    accounts
+        .command("add")
+        .description("Add a new Claude Max account interactively")
+        .action(async () => {
+        const { setupSingleAccount } = await import("./cmd-setup.js");
+        const existing = accountsFileExists() ? loadAccounts() : [];
+        const account = await setupSingleAccount(existing.length + 1);
+        if (!account) {
+            console.log(chalk.yellow("\nNo account added.\n"));
+            return;
+        }
+        // Merge: replace by ID if already exists, otherwise append
+        const merged = [
+            ...existing.filter(a => a.id !== account.id),
+            account,
+        ];
+        saveAccounts(merged);
+        console.log(chalk.green(`\n✓ Account "${account.id}" added (${merged.length} total).\n`));
+        console.log(chalk.gray("  Restart the proxy to load the new account: cc-router start\n"));
+    });
+    // ── accounts remove ───────────────────────────────────────────────────────
+    accounts
+        .command("remove <id>")
+        .description("Remove an account by its ID")
+        .action(async (id) => {
+        if (!accountsFileExists()) {
+            console.log(chalk.yellow("No accounts configured."));
+            return;
+        }
+        const existing = loadAccounts();
+        const filtered = existing.filter(a => a.id !== id);
+        if (filtered.length === existing.length) {
+            console.log(chalk.red(`✗ Account "${id}" not found.`));
+            console.log(chalk.gray(`  Available: ${existing.map(a => a.id).join(", ")}`));
+            process.exit(1);
+        }
+        const { confirm } = await import("@inquirer/prompts");
+        const sure = await confirm({
+            message: `Remove "${id}"? This cannot be undone.`,
+            default: false,
+        });
+        if (!sure) {
+            console.log(chalk.gray("Cancelled."));
+            return;
+        }
+        writeAccountsAtomic(filtered.map(a => ({
+            id: a.id,
+            accessToken: a.tokens.accessToken,
+            refreshToken: a.tokens.refreshToken,
+            expiresAt: a.tokens.expiresAt,
+            scopes: a.tokens.scopes,
+        })));
+        console.log(chalk.green(`✓ Removed "${id}". ${filtered.length} account(s) remaining.`));
+        if (filtered.length === 0) {
+            console.log(chalk.yellow("  No accounts left. Run: cc-router setup"));
+        }
+    });
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+async function fetchLiveStats() {
+    try {
+        const res = await fetch(`http://localhost:${PROXY_PORT}/cc-router/health`, {
+            signal: AbortSignal.timeout(1_000),
+        });
+        if (!res.ok)
+            return null;
+        const data = await res.json();
+        return data.accounts;
+    }
+    catch {
+        return null;
+    }
+}
+function formatMs(ms) {
+    const h = Math.floor(ms / 3_600_000);
+    const m = Math.floor((ms % 3_600_000) / 60_000);
+    return h > 0 ? `${h}h ${m}m` : `${m}m`;
+}

package/dist/cli/cmd-configure.js

@@ -0,0 +1,37 @@
+import chalk from "chalk";
+import { writeClaudeSettings, removeClaudeSettings, readClaudeProxySettings } from "../utils/claude-config.js";
+import { PROXY_PORT, CLAUDE_SETTINGS_PATH } from "../config/paths.js";
+export function registerConfigure(program) {
+    program
+        .command("configure")
+        .description("Update ~/.claude/settings.json to point to the proxy (or remove the config)")
+        .option("--remove", "Remove cc-router settings from ~/.claude/settings.json")
+        .option("--port <port>", "Proxy port to configure", String(PROXY_PORT))
+        .option("--show", "Show current Claude Code proxy settings")
+        .action((opts) => {
+        if (opts.show) {
+            const current = readClaudeProxySettings();
+            if (current.baseUrl) {
+                console.log(chalk.green("  Claude Code is configured to use cc-router:"));
+                console.log(`    ANTHROPIC_BASE_URL  = ${chalk.cyan(current.baseUrl)}`);
+                console.log(`    ANTHROPIC_AUTH_TOKEN = ${chalk.gray(current.authToken ?? "(not set)")}`);
+            }
+            else {
+                console.log(chalk.yellow("  Claude Code is NOT configured to use cc-router."));
+                console.log(chalk.gray(`  Run: cc-router configure`));
+            }
+            return;
+        }
+        if (opts.remove) {
+            removeClaudeSettings();
+            console.log(chalk.green("✓ Removed cc-router settings from ~/.claude/settings.json"));
+            console.log(chalk.gray("  Claude Code will use its default authentication on next launch."));
+            return;
+        }
+        const port = parseInt(opts.port, 10);
+        writeClaudeSettings(port);
+        console.log(chalk.green(`✓ Updated ${CLAUDE_SETTINGS_PATH}`));
+        console.log(chalk.gray(`  ANTHROPIC_BASE_URL  = http://localhost:${port}`));
+        console.log(chalk.gray(`  ANTHROPIC_AUTH_TOKEN = proxy-managed`));
+    });
+}