ai-cc-router 0.2.2 → 0.2.4

package/README.md

@@ -7,6 +7,21 @@ Distribute Claude Code requests across N subscriptions to multiply your throughp
 [![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)
 
+### Features
+
+- **Round-robin token rotation** — distribute requests across 2-20 Claude Max accounts automatically
+- **Transparent proxy** — Claude Code works normally; streaming, thinking, tool use, prompt caching all pass through
+- **Automatic token refresh** — OAuth tokens are refreshed before they expire, saved atomically to disk
+- **Rate limit awareness** — detects 429/529 responses and coolsdown accounts; picks the least-loaded one
+- **Client mode** — connect to a remote CC-Router from any machine with one command (`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 setup` extracts 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** — 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)
+- **Cross-platform** — macOS, Linux, Windows; Node.js 20+
+
 ---
 
 > **Warning**  

package/dist/cli/cmd-client.js

@@ -4,7 +4,7 @@ import { input, confirm } from "@inquirer/prompts";
 import { readConfig, writeConfig } from "../config/manager.js";
 import { writeClaudeSettings, removeClaudeSettings, readClaudeProxySettings } from "../utils/claude-config.js";
 import { isMacos, isWindows } from "../utils/platform.js";
-import { checkMitmproxyInstalled, isCaCertInstalled, generateCaCert, installCaCert, writeAddonScript, startInterceptor, stopInterceptor, isInterceptorRunning, getProcessName, } from "../interceptor/mitmproxy-manager.js";
+import { checkMitmproxyInstalled, isCaCertInstalled, generateCaCert, installCaCert, writeAddonScript, startInterceptor, stopInterceptor, isInterceptorRunning, getProcessName, getNetworkExtensionStatus, openNetworkExtensionSettings, } from "../interceptor/mitmproxy-manager.js";
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 function isClaudeDesktopInstalled() {
     if (isMacos()) {
@@ -112,9 +112,15 @@ export function registerClient(program) {
         writeClaudeSettings(0, url, secret ?? "proxy-managed");
         console.log(chalk.green("✓ Claude Code configured to route through CC-Router"));
         console.log(chalk.gray(`  ANTHROPIC_BASE_URL → ${url}`));
-        // 6. Optionally configure Claude Desktop
-        const wantsDesktop = opts?.desktop ?? (isClaudeDesktopInstalled() &&
-            await confirm({ message: "Also route Claude Desktop (chat + Cowork) through the proxy?", default: false }));
+        // 6. Optionally configure Claude Desktop (Cowork / Agent mode only)
+        let wantsDesktop = opts?.desktop ?? false;
+        if (!opts?.desktop && isClaudeDesktopInstalled()) {
+            printDesktopSupportExplainer();
+            wantsDesktop = await confirm({
+                message: "Route Claude Desktop's Cowork / Agent-mode traffic through CC-Router?",
+                default: false,
+            });
+        }
         if (wantsDesktop) {
             await setupDesktopInterception(url);
             cfg.client.desktopEnabled = true;
@@ -198,7 +204,11 @@ export function registerClient(program) {
                 const status = log.statusCode ?? 0;
                 const statusColor = status >= 500 || status === 0 ? chalk.red : status >= 400 ? chalk.yellow : chalk.green;
                 const duration = log.durationMs ? ` ${chalk.gray(log.durationMs + "ms")}` : "";
-                console.log(`    ${chalk.gray(formatTime(log.ts))}  ${log.accountId.padEnd(18)}  ` +
+                const src = log.source === "cli" ? chalk.blue("cli")
+                    : log.source === "desktop" ? chalk.magenta("dsk")
+                        : log.source === "api" ? chalk.gray("api")
+                            : chalk.gray("   ");
+                console.log(`    ${chalk.gray(formatTime(log.ts))}  ${src} ${log.accountId.padEnd(18)}  ` +
                     `${(log.method ?? "?").padEnd(5)} ${(log.path ?? "?").padEnd(22)}  ` +
                     `${statusColor(String(status))}${duration}`);
             }
@@ -207,16 +217,34 @@ export function registerClient(program) {
             console.log(chalk.gray("\n  No recent activity on the remote proxy."));
         }
         // ── Desktop status ─────────────────────────────────────────────────
-        console.log(chalk.bold("\n  DESKTOP INTERCEPTOR"));
+        console.log(chalk.bold("\n  DESKTOP INTERCEPTOR  (Cowork / Agent mode)"));
         if (cfg.client.desktopEnabled) {
             const running = await isInterceptorRunning();
-            console.log(`    ${running ? chalk.green("● running") : chalk.yellow("○ configured but stopped")}`);
-            if (!running) {
+            if (running) {
+                console.log(`    ${chalk.green("● running")}`);
+            }
+            else {
+                console.log(`    ${chalk.yellow("○ configured but stopped")}`);
                 console.log(chalk.gray("    Start with: cc-router client start-desktop"));
             }
+            // Check Network Extension on macOS
+            if (isMacos()) {
+                const extStatus = await getNetworkExtensionStatus();
+                if (extStatus === "waiting") {
+                    console.log(chalk.red("    ⚠  Network Extension NOT approved — interceptor won't capture traffic!"));
+                    console.log(chalk.gray("    Fix: System Settings → General → Login Items & Extensions → Network Extensions"));
+                }
+                else if (extStatus === "not_installed") {
+                    console.log(chalk.yellow("    ⚠  Network Extension not installed — will be triggered on first start"));
+                }
+                else if (extStatus === "enabled") {
+                    console.log(`    ${chalk.green("✓")} ${chalk.gray("Network Extension: enabled")}`);
+                }
+            }
+            console.log(chalk.gray("    Scope: /v1/messages + /v1/models  (normal chat NOT routed)"));
         }
         else {
-            console.log(`    ${chalk.gray("not configured")}`);
+            console.log(`    ${chalk.gray("not configured — enable with: cc-router client connect --desktop")}`);
         }
         console.log();
         console.log(chalk.gray("  Live dashboard: cc-router status\n"));
@@ -224,16 +252,17 @@ export function registerClient(program) {
     // ── cc-router client start-desktop ──────────────────────────────────────────
     client
         .command("start-desktop")
-        .description("Start mitmproxy interceptor for Claude Desktop")
+        .description("Start mitmproxy interceptor for Claude Desktop (Cowork / Agent mode)")
         .action(async () => {
         const cfg = readConfig();
         if (!cfg.client) {
             console.error(chalk.red("Not connected. Run: cc-router client connect <url>"));
             process.exit(1);
         }
-        if (!await checkMitmproxyInstalled()) {
-            console.error(chalk.red("mitmproxy not found. Install it first:"));
-            console.error(chalk.yellow(isMacos() ? "  brew install mitmproxy" : "  pip install mitmproxy"));
+        if (!(await checkMitmproxyInstalled())) {
+            console.error(chalk.red("\n✗ mitmproxy not found. Install it first:"));
+            console.error(chalk.cyan(isMacos() ? "    brew install mitmproxy" : "    pip install mitmproxy"));
+            console.error();
             process.exit(1);
         }
         if (!cfg.client.desktopEnabled) {
@@ -241,13 +270,52 @@ export function registerClient(program) {
             cfg.client.desktopEnabled = true;
             writeConfig(cfg);
         }
+        // Pre-flight check: verify Network Extension is ready on macOS.
+        // startInterceptor does the same check and throws; we catch and show
+        // a friendlier block here with the open-settings shortcut.
+        if (isMacos()) {
+            const status = await getNetworkExtensionStatus();
+            if (status === "waiting") {
+                console.error(chalk.red("\n✗ Mitmproxy Network Extension is NOT yet approved.\n"));
+                printNetworkExtensionInstructions();
+                const openNow = await confirm({
+                    message: "Open System Settings now?",
+                    default: true,
+                });
+                if (openNow)
+                    await openNetworkExtensionSettings();
+                console.error(chalk.yellow("\n  Re-run `cc-router client start-desktop` after approving.\n"));
+                process.exit(1);
+            }
+            if (status === "not_installed") {
+                console.error(chalk.yellow("\n⚠  Mitmproxy Network Extension is not installed yet."));
+                console.error(chalk.gray("  The first mitmdump run will trigger installation."));
+                console.error(chalk.gray("  Approve it in System Settings when macOS prompts you, then re-run this command.\n"));
+            }
+        }
         const target = cfg.client.remoteUrl;
         const processName = getProcessName();
         console.log(chalk.cyan(`\nStarting mitmproxy interceptor for "${processName}"...`));
-        console.log(chalk.gray(`  Redirecting api.anthropic.com → ${target}\n`));
-        await startInterceptor(target);
-        console.log(chalk.green("✓ Claude Desktop interceptor running"));
-        console.log(chalk.gray("  Open Claude Desktop and send a message to test.\n"));
+        console.log(chalk.gray(`  Redirecting api.anthropic.com/v1/messages → ${target}`));
+        try {
+            await startInterceptor(target);
+        }
+        catch (e) {
+            console.error(chalk.red(`\n✗ Failed to start interceptor:\n`));
+            console.error(chalk.yellow("  " + e.message.split("\n").join("\n  ")));
+            console.error();
+            process.exit(1);
+        }
+        console.log(chalk.green("\n✓ Claude Desktop interceptor running"));
+        console.log();
+        console.log(chalk.bold.yellow("  Next steps:"));
+        console.log("    " + chalk.cyan("1.") + " Quit Claude Desktop completely (⌘Q)");
+        console.log("    " + chalk.cyan("2.") + " Reopen Claude Desktop");
+        console.log("    " + chalk.cyan("3.") + " Use Cowork / Agent mode (Claude Code in Desktop)");
+        console.log();
+        console.log(chalk.gray("  Check routing with:  ") + chalk.cyan("cc-router client status"));
+        console.log(chalk.gray("  Stop interceptor:    ") + chalk.cyan("cc-router client stop-desktop"));
+        console.log();
     });
     // ── cc-router client stop-desktop ───────────────────────────────────────────
     client
@@ -259,53 +327,154 @@ export function registerClient(program) {
     });
 }
 // ─── Desktop setup flow ───────────────────────────────────────────────────────
+/**
+ * Printed before asking the user whether to enable Desktop interception.
+ * The copy is deliberately explicit about WHAT works and WHAT doesn't — users
+ * who expect the normal chat to go through CC-Router will hit confusion fast,
+ * and we can head it off here by framing this as a "Cowork / Agent mode" feature.
+ */
+export function printDesktopSupportExplainer() {
+    console.log(chalk.bold.cyan("\n  🖥  Claude Desktop — what CC-Router can route\n"));
+    console.log("  Claude Desktop does NOT expose ANTHROPIC_BASE_URL, so CC-Router uses\n" +
+        "  mitmproxy to selectively intercept only the traffic it can handle:\n");
+    console.log(chalk.green("  ✓ Cowork / Agent mode       ") + chalk.gray("— /v1/messages (this is what gets routed)"));
+    console.log(chalk.green("  ✓ Claude Code inside Desktop") + chalk.gray("— /v1/messages (same as CLI)"));
+    console.log(chalk.red("  ✗ Normal chat               ") + chalk.gray("— goes to claude.ai webview, NOT redirectable"));
+    console.log();
+    console.log(chalk.gray("  TL;DR: Your LLM-heavy workflows (Cowork, agent tasks, in-Desktop\n" +
+        "  Claude Code) will rotate across your Max accounts via CC-Router.\n" +
+        "  The regular chat sidebar keeps going directly through claude.ai."));
+    console.log();
+}
+/**
+ * Prints the macOS Network Extension approval walkthrough.
+ * This is the #1 gotcha — mitmdump starts silently but captures nothing
+ * until the user flips the toggle in System Settings.
+ */
+export function printNetworkExtensionInstructions() {
+    if (!isMacos())
+        return;
+    console.log(chalk.bold.yellow("\n  ⚠  IMPORTANT — macOS Network Extension approval\n"));
+    console.log("  The first time mitmproxy runs in local mode, macOS installs a");
+    console.log("  Network Extension (" + chalk.cyan("Mitmproxy Redirector") + ") that must be approved");
+    console.log("  manually. " + chalk.red("Without this step, mitmproxy captures ZERO traffic.") + "\n");
+    console.log(chalk.bold("  Steps:"));
+    console.log("    " + chalk.cyan("1.") + " Open " + chalk.bold("System Settings"));
+    console.log("    " + chalk.cyan("2.") + " Go to " + chalk.bold("General → Login Items & Extensions"));
+    console.log("    " + chalk.cyan("3.") + " Scroll to " + chalk.bold("Network Extensions") + " and click the " + chalk.bold("ⓘ") + " button");
+    console.log("    " + chalk.cyan("4.") + " Toggle " + chalk.bold("Mitmproxy Redirector") + " ON");
+    console.log("    " + chalk.cyan("5.") + " Enter your Mac admin password when prompted\n");
+    console.log(chalk.gray("  You only need to do this ONCE per machine.\n"));
+}
 async function setupDesktopInterception(target) {
     console.log(chalk.bold("\n🖥  Claude Desktop Setup\n"));
+    // 0. Explain what actually works before anything else
+    printDesktopSupportExplainer();
+    const proceedWithSetup = await confirm({
+        message: "Continue with Cowork / Agent-mode interception setup?",
+        default: true,
+    });
+    if (!proceedWithSetup) {
+        console.log(chalk.gray("Skipping Desktop setup. You can run it later with: cc-router client start-desktop\n"));
+        return;
+    }
     // 1. Check mitmproxy
-    if (!await checkMitmproxyInstalled()) {
-        console.log(chalk.yellow("mitmproxy is required but not installed."));
+    if (!(await checkMitmproxyInstalled())) {
+        console.log(chalk.yellow("\nmitmproxy is required but not installed."));
         if (isMacos()) {
-            console.log(chalk.cyan("  Install: brew install mitmproxy"));
+            console.log(chalk.cyan("  Install:  brew install mitmproxy"));
         }
         else if (isWindows()) {
-            console.log(chalk.cyan("  Install: pip install mitmproxy"));
+            console.log(chalk.cyan("  Install:  pip install mitmproxy  (or download the installer from mitmproxy.org)"));
         }
         else {
-            console.log(chalk.cyan("  Install: pip install mitmproxy (requires kernel ≥ 6.8)"));
+            console.log(chalk.cyan("  Install:  pip install mitmproxy  (Linux local mode requires kernel ≥ 6.8)"));
         }
         console.log();
-        const proceed = await confirm({ message: "Have you installed mitmproxy?", default: false });
-        if (!proceed || !await checkMitmproxyInstalled()) {
-            console.log(chalk.red("mitmproxy not found. Skipping Desktop setup.\n"));
+        const proceed = await confirm({ message: "Have you installed mitmproxy now?", default: false });
+        if (!proceed || !(await checkMitmproxyInstalled())) {
+            console.log(chalk.red("\nmitmproxy still not found. Skipping Desktop setup.\n"));
+            console.log(chalk.gray("Re-run later with:  cc-router client start-desktop\n"));
             return;
         }
     }
     console.log(chalk.green("✓ mitmproxy found"));
-    // 2. Generate CA cert if needed
+    // 2. Generate CA cert if missing
     if (!isCaCertInstalled()) {
-        console.log(chalk.gray("Generating mitmproxy CA certificate..."));
-        await generateCaCert();
+        console.log(chalk.gray("Generating mitmproxy CA certificate (one-time)..."));
+        try {
+            await generateCaCert();
+            console.log(chalk.green("✓ CA certificate generated"));
+        }
+        catch (e) {
+            console.log(chalk.red(`✗ CA generation failed: ${e.message}`));
+            return;
+        }
+    }
+    else {
+        console.log(chalk.green("✓ CA certificate already present"));
     }
     // 3. Install CA cert (requires sudo)
-    console.log(chalk.yellow("\nInstalling the mitmproxy CA certificate requires admin access."));
-    console.log(chalk.gray("This is needed so Claude Desktop trusts the local interceptor."));
-    const installCa = await confirm({ message: "Install CA certificate now? (requires password)", default: true });
+    console.log();
+    console.log(chalk.yellow("The mitmproxy CA certificate must be trusted by your OS so that"));
+    console.log(chalk.yellow("Claude Desktop accepts the local interceptor. This requires sudo."));
+    const installCa = await confirm({ message: "Install CA certificate now? (asks for admin password)", default: true });
     if (installCa) {
         const ok = await installCaCert();
         if (ok) {
-            console.log(chalk.green("✓ CA certificate installed"));
+            console.log(chalk.green("✓ CA certificate installed in system trust store"));
         }
         else {
-            console.log(chalk.red("✗ CA certificate install failed. You may need to install it manually."));
+            console.log(chalk.red("✗ CA certificate install failed."));
+            console.log(chalk.gray("  Install manually later with:"));
+            console.log(chalk.gray("    sudo security add-trusted-cert -d -r trustRoot \\"));
+            console.log(chalk.gray("      -k /Library/Keychains/System.keychain \\"));
+            console.log(chalk.gray("      ~/.mitmproxy/mitmproxy-ca-cert.pem"));
         }
     }
     // 4. Write addon script
     writeAddonScript(target);
     console.log(chalk.green("✓ Redirect addon configured"));
-    // 5. macOS Network Extension note
+    // 5. macOS Network Extension — THIS is the step people miss
     if (isMacos()) {
-        console.log(chalk.yellow("\n⚠  On first run, macOS will ask to approve mitmproxy's Network Extension."));
-        console.log(chalk.gray("   Go to System Settings → General → Login Items & Extensions → Network Extensions"));
-        console.log(chalk.gray("   and toggle 'Mitmproxy Redirector' on.\n"));
+        printNetworkExtensionInstructions();
+        // Check current status and guide the user if it's not enabled
+        const status = await getNetworkExtensionStatus();
+        if (status === "not_installed") {
+            console.log(chalk.gray("  The Network Extension hasn't been installed yet — it'll be triggered\n" +
+                "  automatically the first time you run `cc-router client start-desktop`.\n" +
+                "  macOS will show a popup — approve it and follow the steps above.\n"));
+        }
+        else if (status === "waiting") {
+            console.log(chalk.red("  ⚠  Network Extension is installed but NOT yet approved.\n"));
+            const openNow = await confirm({
+                message: "Open System Settings now so you can approve it?",
+                default: true,
+            });
+            if (openNow) {
+                await openNetworkExtensionSettings();
+                console.log(chalk.gray("\n  System Settings should now be open."));
+                console.log(chalk.gray("  Toggle 'Mitmproxy Redirector' ON, then come back here.\n"));
+                await confirm({ message: "Done? Press Enter when the toggle is ON", default: true });
+                const newStatus = await getNetworkExtensionStatus();
+                if (newStatus === "enabled") {
+                    console.log(chalk.green("✓ Network Extension is enabled"));
+                }
+                else {
+                    console.log(chalk.yellow(`  Still not enabled (status: ${newStatus})`));
+                    console.log(chalk.gray("  You can re-check later with: cc-router client status"));
+                }
+            }
+        }
+        else if (status === "enabled") {
+            console.log(chalk.green("  ✓ Network Extension is already enabled — you're all set"));
+        }
     }
+    // 6. Remind that Claude Desktop must be restarted for mitmproxy to hook into it
+    console.log();
+    console.log(chalk.bold.yellow("  One more thing:"));
+    console.log(chalk.gray("  After starting the interceptor, you must " + chalk.bold("quit and relaunch Claude Desktop")));
+    console.log(chalk.gray("  (⌘Q in Claude Desktop, then reopen it). mitmproxy only captures"));
+    console.log(chalk.gray("  traffic from processes started AFTER it begins listening."));
+    console.log();
 }

package/dist/cli/cmd-setup.js

@@ -11,7 +11,8 @@ import { loadAccounts, accountsFileExists, readConfig, writeConfig, generateProx
 import { PROXY_PORT } from "../config/paths.js";
 import { DEFAULT_RATE_LIMITS } from "../proxy/types.js";
 import { existsSync } from "fs";
-import { checkMitmproxyInstalled, isCaCertInstalled, generateCaCert, installCaCert, writeAddonScript, } from "../interceptor/mitmproxy-manager.js";
+import { checkMitmproxyInstalled, isCaCertInstalled, generateCaCert, installCaCert, writeAddonScript, getNetworkExtensionStatus, openNetworkExtensionSettings, } from "../interceptor/mitmproxy-manager.js";
+import { printDesktopSupportExplainer, printNetworkExtensionInstructions } from "./cmd-client.js";
 const execFileAsync = promisify(execFile);
 // ─── Public registration ──────────────────────────────────────────────────────
 export function registerSetup(program) {
@@ -567,11 +568,12 @@ async function runClientSetupFromWizard() {
     writeClaudeSettings(0, url, secret ?? "proxy-managed");
     console.log(chalk.green("✓ Claude Code configured"));
     console.log(chalk.gray(`  ANTHROPIC_BASE_URL → ${url}\n`));
-    // ── Claude Desktop question ─────────────────────────────────────────────
+    // ── Claude Desktop (Cowork / Agent mode) ─────────────────────────────────
     const desktopInstalled = isMacos() && existsSync("/Applications/Claude.app");
     if (desktopInstalled) {
+        printDesktopSupportExplainer();
         const wantsDesktop = await confirm({
-            message: "Also route Claude Desktop (chat + Cowork) through the proxy?",
+            message: "Route Claude Desktop's Cowork / Agent-mode traffic through CC-Router?",
             default: false,
         });
         if (wantsDesktop) {
@@ -589,33 +591,82 @@ async function runClientSetupFromWizard() {
     console.log();
 }
 async function setupDesktopFromWizard(target) {
-    console.log(chalk.bold("\n🖥  Claude Desktop Setup\n"));
+    console.log(chalk.bold("\n🖥  Claude Desktop — Cowork / Agent Setup\n"));
+    // 1. Check mitmproxy
     if (!(await checkMitmproxyInstalled())) {
         console.log(chalk.yellow("mitmproxy is required but not installed."));
-        console.log(chalk.cyan("  Install: brew install mitmproxy\n"));
-        const proceed = await confirm({ message: "Have you installed mitmproxy?", default: false });
+        if (isMacos()) {
+            console.log(chalk.cyan("  Install:  brew install mitmproxy\n"));
+        }
+        else {
+            console.log(chalk.cyan("  Install:  pip install mitmproxy\n"));
+        }
+        const proceed = await confirm({ message: "Have you installed mitmproxy now?", default: false });
         if (!proceed || !(await checkMitmproxyInstalled())) {
-            console.log(chalk.red("Skipping Desktop setup.\n"));
+            console.log(chalk.red("Skipping Desktop setup. Re-run with: cc-router client start-desktop\n"));
             return;
         }
     }
     console.log(chalk.green("✓ mitmproxy found"));
+    // 2. CA cert
     if (!isCaCertInstalled()) {
-        console.log(chalk.gray("Generating mitmproxy CA certificate..."));
-        await generateCaCert();
+        console.log(chalk.gray("Generating mitmproxy CA certificate (one-time)..."));
+        try {
+            await generateCaCert();
+            console.log(chalk.green("✓ CA certificate generated"));
+        }
+        catch (e) {
+            console.log(chalk.red(`✗ CA generation failed: ${e.message}`));
+            return;
+        }
+    }
+    else {
+        console.log(chalk.green("✓ CA certificate already present"));
     }
-    console.log(chalk.yellow("\nInstalling the CA certificate requires your admin password."));
+    console.log(chalk.yellow("\nThe CA certificate must be installed in your OS trust store (requires admin)."));
     const doInstall = await confirm({ message: "Install CA certificate now?", default: true });
     if (doInstall) {
         const ok = await installCaCert();
-        console.log(ok ? chalk.green("✓ CA certificate installed") : chalk.red("✗ CA install failed — install manually later"));
+        if (ok) {
+            console.log(chalk.green("✓ CA certificate installed in system trust store"));
+        }
+        else {
+            console.log(chalk.red("✗ CA install failed."));
+            console.log(chalk.gray("  Install manually: sudo security add-trusted-cert -d -r trustRoot \\"));
+            console.log(chalk.gray("    -k /Library/Keychains/System.keychain ~/.mitmproxy/mitmproxy-ca-cert.pem"));
+        }
     }
+    // 3. Addon
     writeAddonScript(target);
     console.log(chalk.green("✓ Redirect addon configured"));
+    // 4. Network Extension walkthrough (macOS)
     if (isMacos()) {
-        console.log(chalk.yellow("\n⚠  On first run macOS will ask to approve mitmproxy's Network Extension."));
-        console.log(chalk.gray("   System Settings → General → Login Items & Extensions → Network Extensions"));
-        console.log(chalk.gray("   Toggle 'Mitmproxy Redirector' on.\n"));
+        printNetworkExtensionInstructions();
+        const status = await getNetworkExtensionStatus();
+        if (status === "not_installed") {
+            console.log(chalk.gray("  The extension will be installed on first `cc-router client start-desktop`.\n" +
+                "  macOS will show a popup — follow the steps above to approve it.\n"));
+        }
+        else if (status === "waiting") {
+            console.log(chalk.red("  ⚠  Extension is installed but NOT approved.\n"));
+            const openNow = await confirm({ message: "Open System Settings to approve it now?", default: true });
+            if (openNow) {
+                await openNetworkExtensionSettings();
+                console.log(chalk.gray("  System Settings should be open. Toggle 'Mitmproxy Redirector' ON.\n"));
+                await confirm({ message: "Done? Press Enter when the toggle is ON", default: true });
+                const newStatus = await getNetworkExtensionStatus();
+                console.log(newStatus === "enabled"
+                    ? chalk.green("  ✓ Network Extension enabled")
+                    : chalk.yellow(`  Still not enabled (status: ${newStatus}) — you can fix later`));
+            }
+        }
+        else if (status === "enabled") {
+            console.log(chalk.green("  ✓ Network Extension already enabled — you're all set\n"));
+        }
+        // Remind to restart Claude Desktop
+        console.log(chalk.bold.yellow("  Remember:"));
+        console.log(chalk.gray("  After starting the interceptor, " + chalk.bold("quit and relaunch Claude Desktop") + " (⌘Q)"));
+        console.log(chalk.gray("  so mitmproxy can hook into the new process.\n"));
     }
 }
 function printBanner() {

package/dist/interceptor/mitmproxy-manager.js

@@ -60,6 +60,64 @@ export async function checkMitmproxyInstalled() {
         return false;
     }
 }
+/**
+ * Check the approval status of the mitmproxy macOS Network Extension.
+ * No-op on Windows/Linux (returns "enabled").
+ *
+ * Parses `systemextensionsctl list` output, looking for the mitmproxy entry.
+ * Status comes from the flags column:
+ *   "* *"   → enabled + active
+ *   "  *"   → active but waiting for user approval
+ */
+export async function getNetworkExtensionStatus() {
+    if (!isMacos())
+        return "enabled"; // Only macOS needs this check
+    try {
+        const { stdout } = await execFileP("systemextensionsctl", ["list"]);
+        const mitmLine = stdout
+            .split("\n")
+            .find((l) => l.toLowerCase().includes("mitmproxy"));
+        if (!mitmLine)
+            return "not_installed";
+        // systemextensionsctl flags are the first two columns; "*" means set.
+        // Order is "enabled active" — both must be "*" for the extension to work.
+        // Example strings seen in the wild:
+        //   "*\t*\tS8XHQB96PW\torg.mitmproxy.macos-redirector..." → enabled
+        //   "\t*\tS8XHQB96PW\torg.mitmproxy.macos-redirector..."  → waiting
+        //
+        // We also accept the human-readable "[activated enabled]" / "[activated waiting for user]"
+        // suffix that newer macOS versions append.
+        if (mitmLine.includes("[activated enabled]"))
+            return "enabled";
+        if (mitmLine.includes("waiting for user"))
+            return "waiting";
+        const cols = mitmLine.split("\t").map((s) => s.trim());
+        const enabled = cols[0] === "*";
+        const active = cols[1] === "*";
+        if (enabled && active)
+            return "enabled";
+        if (!enabled && active)
+            return "waiting";
+        return "not_installed";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** Open the macOS "Login Items & Extensions" settings pane. Best-effort. */
+export async function openNetworkExtensionSettings() {
+    if (!isMacos())
+        return;
+    try {
+        // The x-apple.systempreferences URL opens the right pane in System Settings.
+        // Extensions pane is not directly deep-linkable, so we open the closest one.
+        await execFileP("open", ["x-apple.systempreferences:com.apple.LoginItems-Settings.extension"]);
+    }
+    catch {
+        // If that fails, fall back to opening plain System Settings
+        await execFileP("open", ["/System/Applications/System Settings.app"]).catch(() => { });
+    }
+}
 // ─── CA certificate ───────────────────────────────────────────────────────────
 export function isCaCertInstalled() {
     return existsSync(CA_PATH);
@@ -165,6 +223,24 @@ def request(flow: http.HTTPFlow) -> None:
  * api.anthropic.com traffic to CC-Router via the addon script.
  */
 export async function startInterceptor(target) {
+    // On macOS, verify the Network Extension is enabled before attempting to start.
+    // If it's "waiting", mitmdump starts silently but captures zero traffic.
+    if (isMacos()) {
+        const status = await getNetworkExtensionStatus();
+        if (status === "waiting") {
+            throw new Error("Mitmproxy Network Extension is installed but not yet approved.\n" +
+                "  Open: System Settings → General → Login Items & Extensions → Network Extensions\n" +
+                '  Toggle "Mitmproxy Redirector" ON and enter your admin password.\n' +
+                "  Then re-run this command.");
+        }
+        if (status === "not_installed") {
+            throw new Error("Mitmproxy Network Extension is not installed.\n" +
+                "  Run mitmdump once manually to trigger the installation:\n" +
+                '    mitmdump --mode "local:Claude" --set connection_strategy=lazy\n' +
+                "  macOS will prompt you to approve it in System Settings.\n" +
+                "  Then re-run this command.");
+        }
+    }
     // Ensure addon exists
     if (!existsSync(ADDON_PATH))
         writeAddonScript(target);

package/dist/proxy/server.js

@@ -317,6 +317,11 @@ export async function startServer(opts = {}) {
         }
         req._ccAccount = account;
         req._startTime = Date.now();
+        const source = req.headers["x-claude-code-session-id"]
+            ? "cli"
+            : req.headers["x-api-key"]
+                ? "desktop"
+                : "api";
         req._pendingLog = {
             ts: Date.now(),
             accountId: account.id,
@@ -324,6 +329,7 @@ export async function startServer(opts = {}) {
             type: "route",
             method: req.method,
             path: req.path,
+            source,
         };
         stats.totalRequests++;
         logRoute(account.id, account.requestCount, Math.round((account.tokens.expiresAt - Date.now()) / 60_000));

package/dist/ui/Dashboard.js

@@ -146,6 +146,13 @@ function LogRow({ log, selected }) {
                     : "gray";
     const bg = selected ? "white" : undefined;
     const fg = (c) => selected ? "black" : c;
+    const sourceLabel = log.source === "cli" ? "cli"
+        : log.source === "desktop" ? "dsk"
+            : log.source === "api" ? "api"
+                : "   ";
+    const sourceColor = log.source === "cli" ? "blue"
+        : log.source === "desktop" ? "magenta"
+            : "gray";
     // Per-request token stats
     const inputTok = (log.cacheReadTokens ?? 0) + (log.cacheCreationTokens ?? 0) + (log.inputTokens ?? 0);
     const outputTok = log.outputTokens ?? 0;
@@ -154,7 +161,7 @@ function LogRow({ log, selected }) {
         : cacheHitPct >= 70 ? "green"
             : cacheHitPct >= 30 ? "yellow"
                 : "red";
-    return (_jsxs(Box, { children: [_jsxs(Text, { backgroundColor: bg, color: fg(undefined), children: [selected ? "▶" : " ", " ", time, "  "] }), _jsxs(Text, { backgroundColor: bg, color: fg(typeColor), children: [typeIcon, " "] }), _jsx(Text, { backgroundColor: bg, color: fg("cyan"), children: log.accountId.slice(0, 22).padEnd(22) }), log.method && log.path
+    return (_jsxs(Box, { children: [_jsxs(Text, { backgroundColor: bg, color: fg(undefined), children: [selected ? "▶" : " ", " ", time, "  "] }), _jsxs(Text, { backgroundColor: bg, color: fg(typeColor), children: [typeIcon, " "] }), _jsxs(Text, { backgroundColor: bg, color: fg(sourceColor), children: [sourceLabel, " "] }), _jsx(Text, { backgroundColor: bg, color: fg("cyan"), children: log.accountId.slice(0, 22).padEnd(22) }), log.method && log.path
                 ? _jsxs(Text, { backgroundColor: bg, color: fg("white"), children: [" ", log.method, " ", log.path.padEnd(14)] })
                 : _jsxs(Text, { backgroundColor: bg, color: fg(typeColor), children: [" ", log.type.padEnd(9)] }), log.statusCode !== undefined && (_jsxs(Text, { backgroundColor: bg, color: fg(statusColor), children: [" ", log.statusCode] })), log.durationMs !== undefined && (_jsxs(Text, { backgroundColor: bg, color: fg("gray"), children: [" ", log.durationMs, "ms"] })), cacheHitPct !== null && (_jsxs(Text, { backgroundColor: bg, color: fg(cacheColor), children: [" \u2191", cacheHitPct, "%"] })), (inputTok > 0 || outputTok > 0) && (_jsxs(Text, { backgroundColor: bg, color: fg("gray"), children: [" ", fmtTok(inputTok), "\u2191 ", fmtTok(outputTok), "\u2193"] })), log.details && (_jsxs(Text, { backgroundColor: bg, color: fg("gray"), children: ["  ", log.details] }))] }));
 }
@@ -174,7 +181,7 @@ function DetailPanel({ log }) {
             : log.statusCode >= 500 ? "red"
                 : log.statusCode >= 400 ? "yellow"
                     : "green";
-    return (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, children: [_jsx(Text, { bold: true, color: isError ? "red" : "cyan", children: " DETAILS " }), _jsxs(Box, { marginTop: 1, flexDirection: "column", gap: 0, children: [_jsxs(Box, { gap: 2, children: [_jsx(Field, { label: "Time", value: time }), _jsx(Field, { label: "Account", value: log.accountId })] }), _jsxs(Box, { gap: 2, children: [_jsx(Field, { label: "Method", value: log.method ?? "—" }), _jsx(Field, { label: "Path", value: log.path ?? "—" })] }), _jsxs(Box, { gap: 2, children: [_jsx(FieldColored, { label: "Status", value: statusLabel, color: statusColor }), _jsx(Field, { label: "Duration", value: log.durationMs !== undefined ? `${log.durationMs}ms` : "—" }), _jsx(Field, { label: "Type", value: log.type })] }), log.details && (_jsx(Box, { children: _jsx(Field, { label: "Details", value: log.details }) })), log.cacheReadTokens !== undefined && (_jsx(Box, { gap: 2, children: _jsx(CacheBreakdown, { read: log.cacheReadTokens, created: log.cacheCreationTokens ?? 0, input: log.inputTokens ?? 0, output: log.outputTokens ?? 0 }) }))] })] }));
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, children: [_jsx(Text, { bold: true, color: isError ? "red" : "cyan", children: " DETAILS " }), _jsxs(Box, { marginTop: 1, flexDirection: "column", gap: 0, children: [_jsxs(Box, { gap: 2, children: [_jsx(Field, { label: "Time", value: time }), _jsx(Field, { label: "Account", value: log.accountId })] }), _jsxs(Box, { gap: 2, children: [_jsx(Field, { label: "Method", value: log.method ?? "—" }), _jsx(Field, { label: "Path", value: log.path ?? "—" })] }), _jsxs(Box, { gap: 2, children: [_jsx(FieldColored, { label: "Status", value: statusLabel, color: statusColor }), _jsx(Field, { label: "Duration", value: log.durationMs !== undefined ? `${log.durationMs}ms` : "—" }), _jsx(Field, { label: "Type", value: log.type }), _jsx(Field, { label: "Source", value: sourceFullLabel(log.source) })] }), log.details && (_jsx(Box, { children: _jsx(Field, { label: "Details", value: log.details }) })), log.cacheReadTokens !== undefined && (_jsx(Box, { gap: 2, children: _jsx(CacheBreakdown, { read: log.cacheReadTokens, created: log.cacheCreationTokens ?? 0, input: log.inputTokens ?? 0, output: log.outputTokens ?? 0 }) }))] })] }));
 }
 function Field({ label, value }) {
     return (_jsxs(Box, { children: [_jsxs(Text, { color: "gray", children: [label, ": "] }), _jsx(Text, { color: "white", children: value })] }));
@@ -215,6 +222,16 @@ function fmtTok(n) {
         return `${(n / 1_000).toFixed(1)}k`;
     return String(n);
 }
+// ─── Source label ─────────────────────────────────────────────────────────────
+function sourceFullLabel(source) {
+    if (source === "cli")
+        return "Claude Code";
+    if (source === "desktop")
+        return "Claude Desktop";
+    if (source === "api")
+        return "API";
+    return "—";
+}
 // ─── HTTP status text ─────────────────────────────────────────────────────────
 function httpStatusText(code) {
     const map = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-cc-router",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Round-robin proxy for Claude Max OAuth tokens — use multiple Claude Max accounts with Claude Code",
   "type": "module",
   "bin": {