ai-cc-router 0.2.7 → 0.3.0

package/README.md

@@ -3,10 +3,11 @@
 **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)
 
+![CC-Router Dashboard](assets/dashboard.png)
+
 ### Features
 
 - **Round-robin token rotation** — distribute requests across 2-20 Claude Max accounts automatically
@@ -19,7 +20,7 @@ Distribute Claude Code requests across N subscriptions to multiply your throughp
 - **Live dashboard** — real-time terminal UI showing account health, request counts, token usage, recent activity
 - **Proxy authentication** — optional Bearer / x-api-key secret for internet-exposed deployments
 - **Auto-update** — patch/minor releases install automatically (opt-out available)
-- **Multiple deployment modes** — foreground, PM2 daemon, system service, Docker Compose (with LiteLLM)
+- **Multiple deployment modes** — background daemon, native OS auto-start (launchd/systemd), foreground, Docker Compose
 - **Cross-platform** — macOS, Linux, Windows; Node.js 20+
 
 ---
@@ -114,17 +115,10 @@ Run cc-router on a machine everyone on the team can reach — a home server, a V
 ```bash
 npm install -g ai-cc-router
 cc-router setup          # configure the 3 shared accounts
-cc-router service install # auto-start on boot
+cc-router start          # first run asks: background/boot/server mode — choose "server mode"
 ```
 
-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
-```
+When you enable server mode during `cc-router start`, the proxy automatically binds to all interfaces (`0.0.0.0`) and prints instructions for connecting clients.
 
 #### On each developer's machine
 
@@ -204,9 +198,9 @@ 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:
+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:
 ```bash
-cc-router service install
+cc-router start --reconfigure
 ```
 
 ---
@@ -274,26 +268,27 @@ cc-router setup
 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              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 + restore Claude Code to normal auth
+cc-router stop               Stop proxy (offers to remove auto-start / config)
 cc-router stop --keep-config Stop proxy only (keep settings.json)
-cc-router revert             Restore Claude Code to normal authentication
+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 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 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)
@@ -323,7 +318,7 @@ cc-router docker restart [service]  Restart a service
 Claude Code → cc-router:3456 → api.anthropic.com
 ```
 
-Best for personal use. No Docker required.
+Best for personal use. No Docker required. Runs in the background by default, auto-starts on boot if you choose.
 
 ```bash
 cc-router start
@@ -477,7 +472,9 @@ To stop using cc-router and go back to normal Claude Code authentication:
 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.
+This 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.
 
 ---
 
@@ -530,7 +527,7 @@ CC-Router sends a handful of anonymous lifecycle events to [Aptabase](https://ap
 | `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 6h while the proxy is running              | `uptime_hours`, `account_count`          |
+| `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`).

package/dist/cli/cmd-logs.js

@@ -0,0 +1,85 @@
+import { existsSync, openSync, readSync, closeSync, statSync, watch } from "fs";
+import chalk from "chalk";
+import { LOG_PATH } from "../config/paths.js";
+export function registerLogs(program) {
+    program
+        .command("logs")
+        .description("View proxy logs")
+        .option("--lines <n>", "Number of lines to show (default: 50)", "50")
+        .option("-f, --follow", "Follow log output in real time")
+        .action(async (opts) => {
+        if (!existsSync(LOG_PATH)) {
+            console.log(chalk.yellow("No log file found."));
+            console.log(chalk.gray(`  Expected: ${LOG_PATH}`));
+            console.log(chalk.gray("  Logs are created when running in background mode."));
+            console.log(chalk.gray("  Foreground mode prints directly to this terminal.\n"));
+            return;
+        }
+        const numLines = parseInt(opts.lines, 10) || 50;
+        if (opts.follow) {
+            await tailFollow(numLines);
+        }
+        else {
+            tailStatic(numLines);
+        }
+    });
+}
+/** Print last N lines of the log file using byte-based seeking. */
+function tailStatic(n) {
+    if (!existsSync(LOG_PATH)) {
+        console.log(chalk.gray("No log file found. Is the daemon running?"));
+        return;
+    }
+    const stats = statSync(LOG_PATH);
+    if (stats.size === 0) {
+        console.log(chalk.gray("Log file is empty."));
+        return;
+    }
+    // Read last chunk (up to 64KB should be enough for most tail operations)
+    const CHUNK = Math.min(stats.size, 64 * 1024);
+    const buf = Buffer.alloc(CHUNK);
+    const fd = openSync(LOG_PATH, "r");
+    readSync(fd, buf, 0, CHUNK, stats.size - CHUNK);
+    closeSync(fd);
+    const text = buf.toString("utf-8");
+    const lines = text.split("\n");
+    // Remove first potentially partial line if we didn't read from start
+    if (CHUNK < stats.size)
+        lines.shift();
+    const tail = lines.slice(-n).join("\n");
+    if (tail)
+        process.stdout.write(tail + "\n");
+}
+/** Stream log file and print new lines as they appear. */
+async function tailFollow(initialLines) {
+    // Show initial tail
+    tailStatic(initialLines);
+    console.log(chalk.gray("\n── Following log output (Ctrl+C to stop) ──\n"));
+    if (!existsSync(LOG_PATH)) {
+        console.log(chalk.gray("Waiting for log file..."));
+    }
+    let bytePosition = existsSync(LOG_PATH) ? statSync(LOG_PATH).size : 0;
+    const watcher = watch(LOG_PATH, () => {
+        try {
+            const currentSize = statSync(LOG_PATH).size;
+            if (currentSize > bytePosition) {
+                const buf = Buffer.alloc(currentSize - bytePosition);
+                const fd = openSync(LOG_PATH, "r");
+                readSync(fd, buf, 0, buf.length, bytePosition);
+                closeSync(fd);
+                process.stdout.write(buf.toString("utf-8"));
+                bytePosition = currentSize;
+            }
+            else if (currentSize < bytePosition) {
+                // File was truncated/rotated
+                bytePosition = 0;
+            }
+        }
+        catch { /* file may have been removed */ }
+    });
+    process.on("SIGINT", () => {
+        watcher.close();
+        process.exit(0);
+    });
+    await new Promise(() => { }); // never resolves
+}

package/dist/cli/cmd-setup.js

@@ -1,6 +1,4 @@
 import { select, input, confirm, password } from "@inquirer/prompts";
-import { execFile, spawn } from "child_process";
-import { promisify } from "util";
 import chalk from "chalk";
 import { detectPlatform, isMacos } from "../utils/platform.js";
 import { extractFromKeychain, extractFromCredentialsFile, formatExpiry, redactToken, } from "../utils/token-extractor.js";
@@ -14,7 +12,6 @@ import { existsSync } from "fs";
 import { checkMitmproxyInstalled, isCaCertInstalled, generateCaCert, installCaCert, writeAddonScript, getNetworkExtensionStatus, openNetworkExtensionSettings, } from "../interceptor/mitmproxy-manager.js";
 import { printDesktopSupportExplainer, printNetworkExtensionInstructions } from "./cmd-client.js";
 import { trackEvent } from "../utils/telemetry.js";
-const execFileAsync = promisify(execFile);
 // ─── Public registration ──────────────────────────────────────────────────────
 export function registerSetup(program) {
     program
@@ -110,7 +107,7 @@ export async function setupSingleAccount(index) {
     };
 }
 // ─── Full wizard ──────────────────────────────────────────────────────────────
-async function runSetupWizard({ addMode }) {
+export async function runSetupWizard({ addMode }) {
     const platform = detectPlatform();
     const hasExisting = accountsFileExists();
     const existingClient = readConfig().client;
@@ -305,190 +302,14 @@ async function runPostSetupFlow(accountCount) {
         console.log(chalk.gray(`      ANTHROPIC_BASE_URL  = ${proxyHost}`));
         console.log(chalk.gray(`      ANTHROPIC_AUTH_TOKEN = proxy-managed`));
     }
-    // ── Auto-update preference ──────────────────────────────────────────────
-    const existingCfg = readConfig();
-    if (existingCfg.autoUpdate === undefined) {
-        const enableAutoUpdate = await confirm({
-            message: "Enable auto-updates? (proxy will install patch/minor releases automatically)",
-            default: true,
-        });
-        writeConfig({ ...existingCfg, autoUpdate: enableAutoUpdate });
-        console.log(chalk.gray(`  Auto-update: ${enableAutoUpdate ? chalk.green("enabled") : chalk.gray("disabled")}`));
-        console.log(chalk.gray("  Change later with: cc-router configure --enable-auto-update / --disable-auto-update"));
-    }
-    // 2. Only ask about starting the proxy if it's local
-    console.log(chalk.bold(`\n${"━".repeat(40)}\n  Start the proxy\n${"━".repeat(40)}\n`));
-    // Check if it's already running
-    const alreadyRunning = await isProxyRunning();
-    if (alreadyRunning) {
-        console.log(chalk.green(`  ✓ Proxy is already running on http://localhost:${PROXY_PORT}`));
-        printDone(accountCount);
-        return;
-    }
-    const startChoice = await select({
-        message: "How do you want to run the proxy?",
-        choices: [
-            { name: "Install as system service  (auto-start on boot — recommended)", value: "service" },
-            { name: "Start in background now  (current session only, via PM2)", value: "daemon" },
-            { name: "Start in foreground now  (this terminal, Ctrl+C to stop)", value: "foreground" },
-            { name: "I'll start it manually later", value: "skip" },
-        ],
-    });
-    if (startChoice === "service") {
-        await installService();
-    }
-    else if (startChoice === "daemon") {
-        await startDaemon();
-    }
-    else if (startChoice === "foreground") {
-        printDone(accountCount);
-        console.log(chalk.cyan("\nStarting proxy in foreground...\n"));
-        // Launch start as child — it blocks until Ctrl+C
-        await startForeground();
-        return; // startForeground never returns normally
-    }
     printDone(accountCount);
 }
-// ─── Proxy launch helpers ─────────────────────────────────────────────────────
-async function isProxyRunning() {
-    try {
-        const res = await fetch(`http://localhost:${PROXY_PORT}/cc-router/health`, {
-            signal: AbortSignal.timeout(800),
-        });
-        return res.ok;
-    }
-    catch {
-        return false;
-    }
-}
-async function installService() {
-    console.log(chalk.cyan("\n  Installing as system service via PM2..."));
-    try {
-        // Ensure PM2 is installed
-        await execFileAsync("pm2", ["--version"]).catch(async () => {
-            console.log(chalk.gray("  Installing PM2..."));
-            await execFileAsync("npm", ["install", "-g", "pm2"]);
-        });
-        const { fileURLToPath } = await import("url");
-        const { dirname, join } = await import("path");
-        const __dirname = dirname(fileURLToPath(import.meta.url));
-        const cliEntry = join(__dirname, "index.js");
-        // Start in PM2
-        await execFileAsync("pm2", [
-            "start", cliEntry,
-            "--name", "cc-router",
-            "--interpreter", process.execPath,
-            "--max-memory-restart", "500M",
-            "--", "start",
-        ]).catch(async (err) => {
-            // Already registered — restart instead
-            if (err.message?.includes("already")) {
-                await execFileAsync("pm2", ["restart", "cc-router"]);
-            }
-            else {
-                throw err;
-            }
-        });
-        await execFileAsync("pm2", ["save"]);
-        console.log(chalk.green("  ✓ cc-router registered in PM2 and saved"));
-        // Generate startup hook
-        try {
-            const { stdout, stderr } = await execFileAsync("pm2", ["startup"]);
-            const combined = stdout + stderr;
-            const sudoMatch = combined.match(/sudo\s+\S.+/);
-            if (sudoMatch) {
-                console.log(chalk.yellow("\n  Run this command to complete auto-start setup:"));
-                console.log(chalk.white(`    ${sudoMatch[0]}`));
-                console.log(chalk.gray("  Then run: pm2 save"));
-            }
-            else {
-                console.log(chalk.green("  ✓ Auto-start on boot configured"));
-            }
-        }
-        catch (err) {
-            const combined = (err.stdout ?? "") +
-                (err.stderr ?? "");
-            const sudoMatch = combined.match(/sudo\s+\S.+/);
-            if (sudoMatch) {
-                console.log(chalk.yellow("\n  Run this command to complete auto-start setup:"));
-                console.log(chalk.white(`    ${sudoMatch[0]}`));
-                console.log(chalk.gray("  Then run: pm2 save"));
-            }
-        }
-        // Wait a moment and confirm it started
-        await new Promise(r => setTimeout(r, 1500));
-        const running = await isProxyRunning();
-        if (running) {
-            console.log(chalk.green(`  ✓ Proxy is running on http://localhost:${PROXY_PORT}`));
-        }
-        else {
-            console.log(chalk.yellow("  ⚠ Service registered but proxy not yet responding — it may still be starting."));
-            console.log(chalk.gray("    Check: cc-router service status"));
-        }
-    }
-    catch (err) {
-        console.log(chalk.red(`  ✗ Service install failed: ${err.message}`));
-        console.log(chalk.gray("  Try manually: cc-router service install"));
-    }
-}
-async function startDaemon() {
-    console.log(chalk.cyan("\n  Starting in background via PM2..."));
-    try {
-        const { fileURLToPath } = await import("url");
-        const { dirname, join } = await import("path");
-        const __dirname = dirname(fileURLToPath(import.meta.url));
-        const cliEntry = join(__dirname, "index.js");
-        await execFileAsync("pm2", [
-            "start", cliEntry,
-            "--name", "cc-router",
-            "--interpreter", process.execPath,
-            "--max-memory-restart", "500M",
-            "--", "start",
-        ]).catch(async (err) => {
-            if (err.message?.includes("already")) {
-                await execFileAsync("pm2", ["restart", "cc-router"]);
-            }
-            else {
-                throw err;
-            }
-        });
-        await new Promise(r => setTimeout(r, 1500));
-        const running = await isProxyRunning();
-        if (running) {
-            console.log(chalk.green(`  ✓ Proxy running in background on http://localhost:${PROXY_PORT}`));
-            console.log(chalk.gray("    Logs: pm2 logs cc-router  |  Stop: cc-router stop"));
-        }
-        else {
-            console.log(chalk.yellow("  ⚠ PM2 registered but proxy not yet responding."));
-            console.log(chalk.gray("    Check: pm2 logs cc-router"));
-        }
-    }
-    catch (err) {
-        console.log(chalk.red(`  ✗ Failed to start via PM2: ${err.message}`));
-        console.log(chalk.gray("  PM2 not installed? Run: npm install -g pm2"));
-        console.log(chalk.gray("  Or start manually: cc-router start"));
-    }
-}
-async function startForeground() {
-    const { fileURLToPath } = await import("url");
-    const { dirname, join } = await import("path");
-    const __dirname = dirname(fileURLToPath(import.meta.url));
-    const cliEntry = join(__dirname, "index.js");
-    const child = spawn(process.execPath, [cliEntry, "start"], { stdio: "inherit" });
-    await new Promise((resolve) => {
-        child.on("close", resolve);
-        child.on("error", (err) => {
-            console.error(chalk.red(`  ✗ ${err.message}`));
-            resolve();
-        });
-    });
-}
 // ─── Done banner ──────────────────────────────────────────────────────────────
 function printDone(accountCount) {
     console.log(chalk.bold(`\n${"━".repeat(40)}\n  All done — ${accountCount} account(s) ready\n${"━".repeat(40)}\n`));
-    console.log(`  Dashboard:         ${chalk.cyan("cc-router status")}`);
+    console.log(`  Start the proxy:   ${chalk.cyan("cc-router start")}`);
     console.log(`  Add more accounts: ${chalk.cyan("cc-router setup --add")}`);
-    console.log(`  Stop & revert:     ${chalk.cyan("cc-router revert")}\n`);
+    console.log(`  Dashboard:         ${chalk.cyan("cc-router status")}\n`);
 }
 // ─── Manual token input ───────────────────────────────────────────────────────
 async function promptManualTokens() {