ai-cc-router 0.2.4 → 0.2.6

package/README.md

@@ -513,12 +513,47 @@ Press `q` to quit. Run with `--json` for non-interactive output.
 - 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
+- Anonymous opt-out telemetry via [Aptabase](https://aptabase.com) (see [Telemetry](#telemetry) below)
 
 See [docs/security.md](docs/security.md) for details.
 
 ---
 
+## Telemetry
+
+CC-Router sends a handful of anonymous lifecycle events to [Aptabase](https://aptabase.com) (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`](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 6h while the proxy is running              | `uptime_hours`, `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:
+
+```bash
+# 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=0
+```
+
+Check status anytime: `cc-router telemetry status`.
+
+---
+
 ## Disclaimer
 
 > CC-Router uses the OAuth tokens of your own Claude Max subscriptions.

package/dist/cli/cmd-service.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from "url";
 import { join, dirname } from "path";
 import chalk from "chalk";
 import { detectPlatform } from "../utils/platform.js";
+import { showTelemetryDisclosureIfNeeded } from "../utils/telemetry.js";
 const execFileAsync = promisify(execFile);
 // Resolve the path to the compiled CLI entry point
 const __filename = fileURLToPath(import.meta.url);
@@ -18,6 +19,9 @@ export function registerService(program) {
         .description("Register cc-router to start automatically on system boot")
         .action(async () => {
         console.log(chalk.cyan("\nInstalling cc-router as a system service...\n"));
+        // Show telemetry disclosure once before the service takes over — after
+        // this point output goes to PM2 logs, not the user's terminal.
+        showTelemetryDisclosureIfNeeded();
         // 1. Verify PM2 is installed
         const pm2Version = await getPm2Version();
         if (!pm2Version) {

package/dist/cli/cmd-setup.js

@@ -13,6 +13,7 @@ import { DEFAULT_RATE_LIMITS } from "../proxy/types.js";
 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, showTelemetryDisclosureIfNeeded } from "../utils/telemetry.js";
 const execFileAsync = promisify(execFile);
 // ─── Public registration ──────────────────────────────────────────────────────
 export function registerSetup(program) {
@@ -212,6 +213,8 @@ async function runSetupWizard({ addMode }) {
     console.log(chalk.bold(`\n${"━".repeat(40)}\n  Saving\n${"━".repeat(40)}\n`));
     saveAccounts(merged);
     console.log(chalk.green(`  ✓ ${merged.length} account(s) saved to ~/.cc-router/accounts.json`));
+    showTelemetryDisclosureIfNeeded();
+    void trackEvent("setup_completed", { account_count: merged.length });
     // ─── Post-setup interactive flow ─────────────────────────────────────────
     await runPostSetupFlow(merged.length);
 }

package/dist/cli/cmd-start.js

@@ -2,6 +2,7 @@ import { execFile } from "child_process";
 import { promisify } from "util";
 import chalk from "chalk";
 import { PROXY_PORT, LITELLM_PORT, ACCOUNTS_PATH } from "../config/paths.js";
+import { showTelemetryDisclosureIfNeeded } from "../utils/telemetry.js";
 const execFileAsync = promisify(execFile);
 export function registerStart(program) {
     program
@@ -13,6 +14,9 @@ export function registerStart(program) {
         .option("--accounts <path>", "Path to accounts.json", ACCOUNTS_PATH)
         .action(async (opts) => {
         if (opts.daemon) {
+            // Show telemetry disclosure in the user's terminal before handing off
+            // to PM2 — once the daemon starts, its stdout goes to PM2 logs.
+            showTelemetryDisclosureIfNeeded();
             await startDaemon();
             return;
         }

package/dist/cli/cmd-telemetry.js

@@ -0,0 +1,60 @@
+import chalk from "chalk";
+import { loadTelemetryState, writeTelemetryState, isTelemetryEnabled } from "../config/telemetry.js";
+import { trackEvent } from "../utils/telemetry.js";
+export function registerTelemetry(program) {
+    program
+        .command("telemetry [action]")
+        .description("Manage anonymous usage analytics: on, off, status (default: status)")
+        .action(async (action) => {
+        const resolved = action ?? "status";
+        if (resolved === "status") {
+            showStatus();
+            return;
+        }
+        if (resolved === "on") {
+            const state = loadTelemetryState();
+            state.enabled = true;
+            writeTelemetryState(state);
+            console.log(chalk.green("Telemetry enabled."));
+            console.log(chalk.dim(`Install ID: ${state.installId}`));
+            return;
+        }
+        if (resolved === "off") {
+            // Send one last event so we know about opt-out rates
+            await trackEvent("telemetry_disabled");
+            const state = loadTelemetryState();
+            state.enabled = false;
+            writeTelemetryState(state);
+            console.log(chalk.yellow("Telemetry disabled. No data will be sent."));
+            console.log(chalk.dim("Re-enable anytime with: cc-router telemetry on"));
+            return;
+        }
+        console.error(chalk.red(`Unknown action "${resolved}". Use: on, off, status`));
+        process.exitCode = 1;
+    });
+}
+function showStatus() {
+    const state = loadTelemetryState();
+    const envDisabled = process.env["DO_NOT_TRACK"] === "1" || process.env["CC_ROUTER_TELEMETRY"] === "0";
+    console.log(chalk.bold("Telemetry"));
+    console.log();
+    if (envDisabled) {
+        console.log(`  Status:     ${chalk.yellow("disabled")} (by environment variable)`);
+    }
+    else if (state.enabled) {
+        console.log(`  Status:     ${chalk.green("enabled")}`);
+    }
+    else {
+        console.log(`  Status:     ${chalk.yellow("disabled")}`);
+    }
+    console.log(`  Active:     ${isTelemetryEnabled() ? chalk.green("yes") : chalk.yellow("no")}`);
+    console.log(`  Install ID: ${chalk.dim(state.installId)}`);
+    console.log(`  Since:      ${chalk.dim(state.firstRunAt)}`);
+    console.log();
+    console.log(chalk.dim("  What we send:  version, OS, locale, lifecycle events (start, heartbeat)"));
+    console.log(chalk.dim("  What we DON'T: IPs, tokens, prompts, request content, account names"));
+    console.log(chalk.dim("  Source code:   src/utils/telemetry.ts"));
+    console.log();
+    console.log(chalk.dim("  Disable:  cc-router telemetry off"));
+    console.log(chalk.dim("  Or set:   DO_NOT_TRACK=1  |  CC_ROUTER_TELEMETRY=0"));
+}

package/dist/cli/index.js

@@ -10,6 +10,7 @@ import { registerConfigure } from "./cmd-configure.js";
 import { registerDocker } from "./cmd-docker.js";
 import { registerUpdate } from "./cmd-update.js";
 import { registerClient } from "./cmd-client.js";
+import { registerTelemetry } from "./cmd-telemetry.js";
 import { getCurrentVersion, checkForUpdate, printUpdateBanner } from "../utils/self-update.js";
 const program = new Command();
 program
@@ -42,6 +43,7 @@ registerConfigure(program);
 registerDocker(program);
 registerUpdate(program);
 registerClient(program);
+registerTelemetry(program);
 // Background update check — fires on every CLI invocation, uses 6h disk cache
 // so it's essentially free after the first check. Notify on process exit.
 if (!process.env["NO_UPDATE_NOTIFIER"] && !process.env["CI"]) {

package/dist/config/paths.js

@@ -12,3 +12,6 @@ export const LITELLM_URL = process.env["LITELLM_URL"];
 // Proxy-level config (password, future settings) — separate from accounts.json
 export const CONFIG_PATH = process.env["CONFIG_PATH"] ??
     path.join(CONFIG_DIR, "config.json");
+// Anonymous telemetry state — install id + opt-in flag
+export const TELEMETRY_PATH = process.env["TELEMETRY_PATH"] ??
+    path.join(CONFIG_DIR, "telemetry.json");

package/dist/config/telemetry.js

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync, writeFileSync, renameSync } from "fs";
+import { randomUUID } from "crypto";
+import { TELEMETRY_PATH } from "./paths.js";
+import { ensureConfigDir } from "./manager.js";
+function defaultState() {
+    return {
+        enabled: true,
+        installId: randomUUID(),
+        firstRunAt: new Date().toISOString(),
+        disclosureShown: false,
+    };
+}
+// Read the telemetry state, creating and persisting a fresh one on first run.
+// Malformed files are treated as missing so a corrupted file can't crash the CLI.
+export function loadTelemetryState() {
+    if (!existsSync(TELEMETRY_PATH)) {
+        const state = defaultState();
+        writeTelemetryState(state);
+        return state;
+    }
+    try {
+        const raw = JSON.parse(readFileSync(TELEMETRY_PATH, "utf-8"));
+        // Fill any missing fields to keep the file forward-compatible
+        const state = {
+            enabled: raw.enabled ?? true,
+            installId: raw.installId ?? randomUUID(),
+            firstRunAt: raw.firstRunAt ?? new Date().toISOString(),
+            disclosureShown: raw.disclosureShown ?? false,
+        };
+        if (!raw.installId || raw.disclosureShown === undefined) {
+            writeTelemetryState(state);
+        }
+        return state;
+    }
+    catch {
+        const state = defaultState();
+        writeTelemetryState(state);
+        return state;
+    }
+}
+// Atomic write: .tmp + rename, same pattern as writeAccountsAtomic
+export function writeTelemetryState(state) {
+    ensureConfigDir();
+    const tmp = TELEMETRY_PATH + ".tmp";
+    writeFileSync(tmp, JSON.stringify(state, null, 2), "utf-8");
+    renameSync(tmp, TELEMETRY_PATH);
+}
+// Returns true only if the user has not opted out through any mechanism:
+//   - DO_NOT_TRACK=1     (de-facto standard)
+//   - CC_ROUTER_TELEMETRY=0  (project-specific override)
+//   - `cc-router telemetry off` (persisted enabled: false)
+export function isTelemetryEnabled() {
+    if (process.env["DO_NOT_TRACK"] === "1")
+        return false;
+    if (process.env["CC_ROUTER_TELEMETRY"] === "0")
+        return false;
+    try {
+        return loadTelemetryState().enabled;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/proxy/server.js

@@ -6,6 +6,8 @@ import { TokenPool } from "./token-pool.js";
 import { needsRefresh, refreshAccountToken, saveAccounts, startRefreshLoop } from "./token-refresher.js";
 import { loadAccounts, accountsFileExists, readAccountsFromPath, readConfig } from "../config/manager.js";
 import { checkForUpdate, performUpdate, restartSelf } from "../utils/self-update.js";
+import { trackEvent, startHeartbeat, showTelemetryDisclosureIfNeeded } from "../utils/telemetry.js";
+import { loadTelemetryState } from "../config/telemetry.js";
 import { logRoute, logError, logStartup } from "./logger.js";
 import { stats } from "./stats.js";
 import { PROXY_PORT, LITELLM_URL } from "../config/paths.js";
@@ -383,5 +385,25 @@ export async function startServer(opts = {}) {
         logStartup(port, host, mode, target, accounts.length);
         if (autoUpdate)
             console.log(chalk.gray("  Auto-update: enabled (patch/minor)"));
+        // Anonymous telemetry — fire-and-forget, never blocks proxy startup.
+        // Show the disclosure on the very first start (covers existing users
+        // upgrading from versions before telemetry existed) before sending anything.
+        try {
+            showTelemetryDisclosureIfNeeded();
+            const telemetryState = loadTelemetryState();
+            // First-run detection: if the install is brand new, emit app_started too
+            const firstRunAge = Date.now() - new Date(telemetryState.firstRunAt).getTime();
+            if (firstRunAge < 5 * 60 * 1000) {
+                void trackEvent("app_started", { first_run: true });
+            }
+            void trackEvent("proxy_started", {
+                account_count: accounts.length,
+                mode,
+            });
+            startHeartbeat(accounts.length);
+        }
+        catch {
+            // never let telemetry break the proxy
+        }
     });
 }

package/dist/utils/telemetry.js

@@ -0,0 +1,117 @@
+import os from "os";
+import chalk from "chalk";
+import { isTelemetryEnabled, loadTelemetryState, writeTelemetryState } from "../config/telemetry.js";
+import { detectPlatform } from "./platform.js";
+import { getCurrentVersion } from "./self-update.js";
+// ─── Aptabase configuration ──────────────────────────────────────────────────
+// Aptabase is a privacy-first, open source analytics service.
+// The full payload we send is documented below — search for "trackEvent" calls
+// in the codebase to audit every event.  Nothing here contains PII.
+const APTABASE_APP_KEY = "A-EU-1060569594";
+const APTABASE_ENDPOINT = "https://eu.aptabase.com/api/v0/event";
+const TIMEOUT_MS = 3_000;
+function getOsName() {
+    switch (detectPlatform()) {
+        case "macos": return "macOS";
+        case "linux": return "Linux";
+        case "windows": return "Windows";
+    }
+}
+function getLocale() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().locale;
+    }
+    catch {
+        return process.env["LANG"]?.split(".")[0] ?? "unknown";
+    }
+}
+function getSystemProps() {
+    return {
+        isDebug: false,
+        locale: getLocale(),
+        osName: getOsName(),
+        osVersion: os.release(),
+        appVersion: getCurrentVersion(),
+        engineName: "node",
+        engineVersion: process.versions.node,
+        sdkVersion: `cc-router@${getCurrentVersion()}`,
+    };
+}
+// Session ID: <installId>-<epoch-hours>.  This groups events that belong to the
+// same "session" (proxy run) without leaking any timing precision finer than 1h.
+function getSessionId(installId) {
+    const epochHours = Math.floor(Date.now() / 3_600_000);
+    return `${installId}-${epochHours}`;
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+// Fire-and-forget: never throws, never blocks the caller.  If telemetry is
+// disabled (env var or opt-out) this is a synchronous no-op.
+export async function trackEvent(eventName, props) {
+    try {
+        if (!isTelemetryEnabled())
+            return;
+        const state = loadTelemetryState();
+        const body = {
+            timestamp: new Date().toISOString(),
+            sessionId: getSessionId(state.installId),
+            eventName,
+            systemProps: getSystemProps(),
+            props: props ?? {},
+        };
+        await fetch(APTABASE_ENDPOINT, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "App-Key": APTABASE_APP_KEY,
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+    }
+    catch {
+        // Silently swallow — telemetry must never disrupt the proxy
+    }
+}
+// Start a heartbeat that fires every 6 hours while the proxy is running.
+// Uses .unref() so the timer does not prevent Node from exiting.
+export function startHeartbeat(accountCount) {
+    const startTime = Date.now();
+    const timer = setInterval(() => {
+        const uptimeHours = Math.floor((Date.now() - startTime) / 3_600_000);
+        trackEvent("proxy_heartbeat", {
+            uptime_hours: uptimeHours,
+            account_count: accountCount,
+        });
+    }, 6 * 60 * 60 * 1000);
+    timer.unref();
+}
+// One-time disclosure shown the very first time CC-Router runs after install
+// or upgrade. Idempotent — gated by telemetry.disclosureShown so it's safe to
+// call from multiple entry points (setup wizard, foreground start, daemon
+// start, service install). Returns true if the disclosure was just shown.
+export function showTelemetryDisclosureIfNeeded() {
+    try {
+        const state = loadTelemetryState();
+        if (state.disclosureShown)
+            return false;
+        console.log();
+        console.log(chalk.dim("─".repeat(60)));
+        console.log(chalk.bold("  Anonymous usage analytics"));
+        console.log();
+        console.log("  CC-Router sends anonymous lifecycle events (version, OS,");
+        console.log("  startup, heartbeat) to help us understand usage and prioritize");
+        console.log("  improvements. No IPs, no tokens, no prompts, no request content.");
+        console.log();
+        console.log(`  Disable:    ${chalk.cyan("cc-router telemetry off")}`);
+        console.log(`  Or set:     ${chalk.cyan("DO_NOT_TRACK=1")}   |   ${chalk.cyan("CC_ROUTER_TELEMETRY=0")}`);
+        console.log(`  Source:     ${chalk.dim("src/utils/telemetry.ts")}`);
+        console.log(chalk.dim("─".repeat(60)));
+        console.log();
+        state.disclosureShown = true;
+        writeTelemetryState(state);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

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