ccusage-tracker 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# ccusage-tracker
+
+CLI for [ccusage-tracker](https://github.com/ericcai0814/ccusage-tracker) — a self-hosted Claude Code usage tracker for teams.
+
+Install Claude Code SessionStart/SessionEnd hooks that report token usage to a self-hosted tracker server. Runs on macOS, Linux, and Windows.
+
+## Quick start
+
+```bash
+npx ccusage-tracker setup
+```
+
+You'll be asked for your name, the team's server URL, and a team key (ask your admin).
+
+## Commands
+
+```
+ccusage-tracker setup    Install hooks and configure server connection
+ccusage-tracker report   View team token usage report
+ccusage-tracker status   Check current configuration status
+```
+
+After installation, the binary is also available as `tracker` (if installed globally with `npm i -g ccusage-tracker`).
+
+## What it does
+
+`setup` writes a config file to `~/.config/ccusage-tracker/config.json` and adds two hooks to your Claude Code `~/.claude/settings.json`:
+
+- **SessionStart** — records the model at session start
+- **SessionEnd** — POSTs token usage (and session metrics in 0.2.1+) to your team's tracker server
+
+Hook scripts are downloaded from your tracker server, so they always match the server version.
+
+## Requirements
+
+- Node.js 18+
+- A running ccusage-tracker server (see [main repo](https://github.com/ericcai0814/ccusage-tracker) for self-hosting)
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+
+// src/commands/setup.ts
+import { createInterface } from "node:readline";
+
+// src/config.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+function getConfigDir() {
+  return join(homedir(), ".config", "ccusage-tracker");
+}
+function getConfigPath() {
+  return join(getConfigDir(), "config.json");
+}
+function readConfig() {
+  const path = getConfigPath();
+  if (!existsSync(path))
+    return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writeConfig(config) {
+  const dir = getConfigDir();
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(getConfigPath(), JSON.stringify(config, null, 2) + `
+`);
+}
+
+// src/hooks.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, copyFileSync, mkdirSync as mkdirSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+import { homedir as homedir2 } from "node:os";
+function getClaudeSettingsPath() {
+  return join2(homedir2(), ".claude", "settings.json");
+}
+function getHookCommand() {
+  return "node " + join2(homedir2(), ".config", "ccusage-tracker", "session-end.mjs");
+}
+function getStartHookCommand() {
+  return "node " + join2(homedir2(), ".config", "ccusage-tracker", "session-start.mjs");
+}
+function isCcusageTrackerHook(command) {
+  return !!command && command.includes("ccusage-tracker");
+}
+function appendHookIfMissing(existing, command) {
+  const present = existing.some((m) => m.hooks?.some((h) => isCcusageTrackerHook(h.command)));
+  if (present) {
+    return { matchers: existing, installed: false };
+  }
+  const newMatcher = {
+    matcher: "",
+    hooks: [{ type: "command", command }]
+  };
+  return { matchers: [...existing, newMatcher], installed: true };
+}
+function applyTrackerHooks(settings) {
+  const start = appendHookIfMissing(settings.hooks?.SessionStart ?? [], getStartHookCommand());
+  const end = appendHookIfMissing(settings.hooks?.SessionEnd ?? [], getHookCommand());
+  const updated = start.installed || end.installed ? {
+    ...settings,
+    hooks: {
+      ...settings.hooks,
+      SessionStart: start.matchers,
+      SessionEnd: end.matchers
+    }
+  } : settings;
+  return {
+    updated,
+    sessionStartInstalled: start.installed,
+    sessionEndInstalled: end.installed
+  };
+}
+function installHook(scripts) {
+  const settingsPath = getClaudeSettingsPath();
+  let settings = {};
+  let backedUp = false;
+  if (existsSync2(settingsPath)) {
+    const raw = readFileSync2(settingsPath, "utf-8");
+    settings = JSON.parse(raw);
+    const backupPath = settingsPath + ".backup";
+    copyFileSync(settingsPath, backupPath);
+    backedUp = true;
+  }
+  const destDir = join2(homedir2(), ".config", "ccusage-tracker");
+  mkdirSync2(destDir, { recursive: true });
+  writeFileSync2(join2(destDir, "session-end.mjs"), scripts.sessionEnd);
+  writeFileSync2(join2(destDir, "session-start.mjs"), scripts.sessionStart);
+  const { updated, sessionStartInstalled, sessionEndInstalled } = applyTrackerHooks(settings);
+  if (sessionStartInstalled || sessionEndInstalled) {
+    writeFileSync2(settingsPath, JSON.stringify(updated, null, 2) + `
+`);
+  }
+  return { sessionEndInstalled, sessionStartInstalled, backedUp };
+}
+function isHookInstalled() {
+  const settingsPath = getClaudeSettingsPath();
+  if (!existsSync2(settingsPath))
+    return false;
+  try {
+    const settings = JSON.parse(readFileSync2(settingsPath, "utf-8"));
+    return settings.hooks?.SessionEnd?.some((m) => m.hooks?.some((h) => isCcusageTrackerHook(h.command))) ?? false;
+  } catch {
+    return false;
+  }
+}
+
+// src/commands/setup.ts
+function defaultPrompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+async function defaultCheckServer(serverUrl) {
+  try {
+    const res = await fetch(`${serverUrl}/api/health`, { signal: AbortSignal.timeout(5000) });
+    const body = await res.json();
+    return body.ok === true;
+  } catch {
+    return false;
+  }
+}
+function defaultCheckCcusage() {
+  try {
+    Bun.spawnSync(["ccusage", "--version"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function defaultFetchHookScript(serverUrl, scriptName) {
+  try {
+    const res = await fetch(`${serverUrl}/scripts/${scriptName}`, { signal: AbortSignal.timeout(1e4) });
+    if (!res.ok)
+      return null;
+    return await res.text();
+  } catch {
+    return null;
+  }
+}
+var defaultDeps = {
+  prompt: defaultPrompt,
+  writeConfig,
+  installHook,
+  fetchHookScript: defaultFetchHookScript,
+  checkServer: defaultCheckServer,
+  checkCcusage: defaultCheckCcusage,
+  log: (msg) => console.log(msg),
+  warn: (msg) => console.warn(msg),
+  exit: (code) => process.exit(code)
+};
+async function setupCommand(overrides) {
+  const deps = { ...defaultDeps, ...overrides };
+  deps.log(`ccusage-tracker setup
+`);
+  const name = await deps.prompt("Your name: ");
+  if (!name) {
+    deps.warn("Name is required.");
+    deps.exit(1);
+    return;
+  }
+  const serverUrl = await deps.prompt("Server URL (e.g. https://tracker.example.com): ");
+  if (!serverUrl) {
+    deps.warn("Server URL is required.");
+    deps.exit(1);
+    return;
+  }
+  const teamKey = await deps.prompt("Team Key (ask your admin): ");
+  if (!teamKey) {
+    deps.warn("Team Key is required.");
+    deps.exit(1);
+    return;
+  }
+  const config = {
+    server_url: serverUrl.replace(/\/+$/, ""),
+    team_key: teamKey,
+    member_name: name
+  };
+  deps.writeConfig(config);
+  deps.log(`
+Config saved.`);
+  const [sessionEnd, sessionStart] = await Promise.all([
+    deps.fetchHookScript(config.server_url, "session-end.mjs"),
+    deps.fetchHookScript(config.server_url, "session-start.mjs")
+  ]);
+  if (sessionEnd && sessionStart) {
+    try {
+      const { sessionEndInstalled, sessionStartInstalled, backedUp } = deps.installHook({
+        sessionEnd,
+        sessionStart
+      });
+      if (sessionEndInstalled || sessionStartInstalled) {
+        deps.log("SessionStart + SessionEnd hooks installed." + (backedUp ? " (settings.json backed up)" : ""));
+      } else {
+        deps.log("SessionStart + SessionEnd hooks already installed.");
+      }
+    } catch (err) {
+      deps.warn("Warning: Could not install hooks automatically. " + err.message);
+    }
+  } else {
+    deps.warn("Warning: Could not download hook scripts from " + config.server_url);
+  }
+  const serverOk = await deps.checkServer(config.server_url);
+  if (serverOk) {
+    deps.log("Server is reachable.");
+  } else {
+    deps.warn("Warning: Server is not reachable at " + config.server_url);
+  }
+  const hasCcusage = deps.checkCcusage();
+  if (hasCcusage) {
+    deps.log("ccusage is installed.");
+  } else {
+    deps.warn("Warning: ccusage not found. Install with: npx ccusage@latest");
+  }
+  deps.log(`
+Setup complete!`);
+}
+
+// src/commands/report.ts
+function padRight(str, len) {
+  return str.length >= len ? str : str + " ".repeat(len - str.length);
+}
+function padLeft(str, len) {
+  return str.length >= len ? str : " ".repeat(len - str.length) + str;
+}
+function formatTable(data) {
+  const lines = [];
+  lines.push(`Period: ${data.period} (${data.from} ~ ${data.to})`);
+  lines.push(`Total Cost: $${data.total_cost_usd.toFixed(2)}  |  Total Tokens: ${data.total_tokens.toLocaleString()}  |  Active Members: ${data.active_members}`);
+  lines.push("");
+  if (data.members.length === 0) {
+    lines.push("No usage data for this period.");
+    return lines.join(`
+`);
+  }
+  const header = [
+    padRight("Member", 15),
+    padLeft("Input", 12),
+    padLeft("Output", 12),
+    padLeft("Cache Create", 14),
+    padLeft("Cache Read", 12),
+    padLeft("Cost", 10)
+  ].join("  ");
+  const separator = "-".repeat(header.length);
+  lines.push(header);
+  lines.push(separator);
+  for (const m of data.members) {
+    lines.push([
+      padRight(m.member_name, 15),
+      padLeft(m.input_tokens.toLocaleString(), 12),
+      padLeft(m.output_tokens.toLocaleString(), 12),
+      padLeft(m.cache_creation_tokens.toLocaleString(), 14),
+      padLeft(m.cache_read_tokens.toLocaleString(), 12),
+      padLeft(`$${m.total_cost_usd.toFixed(2)}`, 10)
+    ].join("  "));
+  }
+  return lines.join(`
+`);
+}
+async function reportCommand(args) {
+  const config = readConfig();
+  if (!config) {
+    console.error("Not configured. Run `tracker setup` first.");
+    process.exit(1);
+  }
+  let period = "month";
+  let jsonOutput = false;
+  for (let i = 0;i < args.length; i++) {
+    if (args[i] === "--period" && args[i + 1]) {
+      period = args[i + 1];
+      i++;
+    }
+    if (args[i] === "--json") {
+      jsonOutput = true;
+    }
+  }
+  try {
+    const res = await fetch(`${config.server_url}/api/report/summary?period=${period}`, {
+      headers: { Authorization: `Bearer ${config.team_key}` },
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      console.error(`Server error: ${res.status}`, body);
+      process.exit(1);
+    }
+    const data = await res.json();
+    if (jsonOutput) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      console.log(formatTable(data));
+    }
+  } catch (err) {
+    console.error("Failed to fetch report:", err.message);
+    process.exit(1);
+  }
+}
+
+// src/commands/status.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
+import { join as join3, dirname } from "node:path";
+async function statusCommand() {
+  const configPath = getConfigPath();
+  const config = readConfig();
+  console.log(`ccusage-tracker status
+`);
+  if (existsSync3(configPath)) {
+    console.log(`Config: ${configPath} (exists)`);
+  } else {
+    console.log(`Config: ${configPath} (not found)`);
+    console.log("\nRun `tracker setup` to configure.");
+    return;
+  }
+  if (config) {
+    console.log(`  Member: ${config.member_name}`);
+    console.log(`  Server: ${config.server_url}`);
+    console.log(`  Team Key: ${config.team_key.slice(0, 15)}...`);
+  }
+  const hookInstalled = isHookInstalled();
+  console.log(`
+Hook: ${hookInstalled ? "installed" : "not installed"}`);
+  if (config) {
+    try {
+      const res = await fetch(`${config.server_url}/api/health`, {
+        signal: AbortSignal.timeout(5000)
+      });
+      const body = await res.json();
+      if (body.ok) {
+        console.log(`Server: reachable (v${body.version || "unknown"})`);
+      } else {
+        console.log("Server: responded but not healthy");
+      }
+    } catch {
+      console.log("Server: unreachable");
+    }
+  }
+  const bufferPath = join3(dirname(configPath), "buffer.jsonl");
+  if (existsSync3(bufferPath)) {
+    const content = readFileSync3(bufferPath, "utf-8").trim();
+    const lineCount = content ? content.split(`
+`).length : 0;
+    console.log(`Buffer: ${lineCount} pending entr${lineCount === 1 ? "y" : "ies"} (${bufferPath})`);
+  } else {
+    console.log("Buffer: none");
+  }
+  try {
+    const result = Bun.spawnSync(["ccusage", "--version"]);
+    const version = new TextDecoder().decode(result.stdout).trim();
+    console.log(`ccusage: installed (${version || "version unknown"})`);
+  } catch {
+    console.log("ccusage: not found (install with: npx ccusage@latest)");
+  }
+}
+
+// src/index.ts
+var args = process.argv.slice(2);
+var command = args[0];
+switch (command) {
+  case "setup":
+    await setupCommand();
+    break;
+  case "report":
+    await reportCommand(args.slice(1));
+    break;
+  case "status":
+    await statusCommand();
+    break;
+  default:
+    console.log(`ccusage-tracker CLI
+`);
+    console.log(`Usage: tracker <command>
+`);
+    console.log("Commands:");
+    console.log("  setup    Configure hook and server connection");
+    console.log("  report   View team token usage report");
+    console.log("  status   Check current configuration status");
+    process.exit(command ? 1 : 0);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "ccusage-tracker",
+  "version": "0.1.0",
+  "description": "CLI for ccusage-tracker — install Claude Code SessionStart/SessionEnd hooks to report token usage to a self-hosted team tracker.",
+  "type": "module",
+  "bin": {
+    "ccusage-tracker": "dist/index.js",
+    "tracker": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target node",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ericcai0814/ccusage-tracker.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/ericcai0814/ccusage-tracker#readme",
+  "bugs": {
+    "url": "https://github.com/ericcai0814/ccusage-tracker/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "ccusage",
+    "tracker",
+    "usage",
+    "tokens",
+    "cli",
+    "hook"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "bun-types": "latest",
+    "typescript": "^5.8.0"
+  }
+}