my-llm-footprint 0.1.0

package/bin/init.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+/**
+ * my-llm-footprint CLI
+ *
+ * Commands:
+ *   init        (default) — validates API key, writes config, installs Claude hook
+ *   uninstall   — removes the hook and config
+ *
+ * Node.js built-ins only. Requires Node 18+ for fetch().
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import readline from 'readline';
+import { fileURLToPath } from 'url';
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const HOME = os.homedir();
+const CONFIG_DIR = path.join(HOME, '.config', 'my-llm-footprint');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+const CLAUDE_SETTINGS_PATH = path.join(HOME, '.claude', 'settings.json');
+
+const ENDPOINT = process.env.LLM_FOOTPRINT_ENDPOINT || 'https://llm-usages.mattjones.wales';
+
+// Resolve the absolute path of the hooks directory relative to this file.
+// import.meta.url → file:///…/packages/my-llm-footprint/bin/init.js
+const PACKAGE_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..');
+const HOOK_SCRIPT = path.join(PACKAGE_ROOT, 'hooks', 'claude-stop.js');
+const HOOK_COMMAND = `node ${HOOK_SCRIPT}`;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Prompt the user for a single line of input.
+ * @param {string} question
+ * @returns {Promise<string>}
+ */
+function prompt(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Read and parse a JSON file, returning null on any error.
+ * @param {string} filePath
+ * @returns {object | null}
+ */
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write an object as pretty-printed JSON, creating parent dirs as needed.
+ * @param {string} filePath
+ * @param {object} data
+ */
+function writeJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n');
+}
+
+// ---------------------------------------------------------------------------
+// init command
+// ---------------------------------------------------------------------------
+
+async function runInit() {
+  console.log('my-llm-footprint setup\n');
+
+  const apiKey = await prompt('Enter your API key: ');
+
+  if (!apiKey) {
+    console.error('Usage: my-llm-footprint init');
+    console.error('An API key is required.');
+    process.exit(1);
+  }
+
+  // --- Validate key ---
+  let userName;
+  try {
+    const res = await fetch(`${ENDPOINT}/api/v1/ingest/verify`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(15000),
+    });
+
+    if (!res.ok) {
+      console.error(`Invalid API key (HTTP ${res.status}).`);
+      process.exit(1);
+    }
+
+    /** @type {{ user: string }} — matches VerifyResponse from @my-llm-footprint/shared */
+    const body = await res.json();
+    userName = body.user ?? 'unknown';
+  } catch (err) {
+    console.error(`Failed to validate API key: ${err.message}`);
+    process.exit(1);
+  }
+
+  console.log(`API key validated — welcome, ${userName}!`);
+
+  // --- Write config ---
+  const config = { apiKey, endpoint: ENDPOINT };
+  writeJson(CONFIG_PATH, config);
+
+  // --- Update ~/.claude/settings.json ---
+  let settings = readJson(CLAUDE_SETTINGS_PATH) ?? {};
+
+  // Ensure hooks.Stop is an array
+  if (!settings.hooks) settings.hooks = {};
+  if (!Array.isArray(settings.hooks.Stop)) {
+    settings.hooks.Stop = settings.hooks.Stop ? [settings.hooks.Stop] : [];
+  }
+
+  // Check whether our hook is already present
+  const alreadyInstalled = settings.hooks.Stop.some((entry) => {
+    const hooks = Array.isArray(entry?.hooks) ? entry.hooks : [];
+    return hooks.some((h) => typeof h.command === 'string' && h.command.includes('my-llm-footprint'));
+  });
+
+  if (alreadyInstalled) {
+    console.log('Hook already installed — skipping.');
+  } else {
+    settings.hooks.Stop.push({
+      hooks: [{ type: 'command', command: HOOK_COMMAND }],
+    });
+    writeJson(CLAUDE_SETTINGS_PATH, settings);
+    console.log('Claude Stop hook installed.');
+  }
+
+  // --- Done ---
+  console.log(`\nDone! Tracking usage for ${userName}.`);
+  console.log(`View your dashboard: ${ENDPOINT}/dashboard`);
+}
+
+// ---------------------------------------------------------------------------
+// uninstall command
+// ---------------------------------------------------------------------------
+
+function runUninstall() {
+  // Remove hook from settings
+  const settings = readJson(CLAUDE_SETTINGS_PATH);
+  if (settings?.hooks?.Stop && Array.isArray(settings.hooks.Stop)) {
+    const before = settings.hooks.Stop.length;
+    settings.hooks.Stop = settings.hooks.Stop.filter((entry) => {
+      const hooks = Array.isArray(entry?.hooks) ? entry.hooks : [];
+      return !hooks.some((h) => typeof h.command === 'string' && h.command.includes('my-llm-footprint'));
+    });
+    if (settings.hooks.Stop.length !== before) {
+      writeJson(CLAUDE_SETTINGS_PATH, settings);
+      console.log('Removed hook from ~/.claude/settings.json');
+    }
+  }
+
+  // Remove config file
+  try {
+    fs.rmSync(CONFIG_PATH, { force: true });
+    console.log('Removed config file.');
+  } catch (err) {
+    console.error(`Could not remove config: ${err.message}`);
+  }
+
+  console.log('Uninstalled my-llm-footprint');
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === '--help' || command === '-h') {
+  console.log(`my-llm-footprint — track your Claude AI usage
+
+Usage:
+  my-llm-footprint [init]     Set up tracking (default command)
+  my-llm-footprint uninstall  Remove hook and config
+  my-llm-footprint --help     Show this help
+
+Description:
+  init        Prompts for an API key, validates it, writes
+              ~/.config/my-llm-footprint/config.json, and installs
+              a Claude Code Stop hook so every session is reported.
+
+  uninstall   Removes the Stop hook from ~/.claude/settings.json
+              and deletes ~/.config/my-llm-footprint/config.json.
+`);
+  process.exit(0);
+}
+
+if (!command || command === 'init') {
+  runInit().catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+  });
+} else if (command === 'uninstall') {
+  runUninstall();
+} else {
+  console.error(`Unknown command: ${command}`);
+  console.error('Run with --help for usage.');
+  process.exit(1);
+}

package/hooks/claude-stop.js

@@ -0,0 +1,414 @@
+#!/usr/bin/env node
+/**
+ * Claude Code hook: my-llm-footprint token reporter.
+ *
+ * Runs on every Claude Code Stop event.
+ * - Reads JSON from stdin (transcript_path, session_id)
+ * - Parses the JSONL transcript to extract token usage
+ * - POSTs raw counts to the configured API endpoint
+ * - Prints an energy/water summary to stderr
+ * - On failure: writes event to ~/.config/my-llm-footprint/pending.json
+ * - On success: flushes any pending events from the queue
+ *
+ * No external dependencies — Node.js built-ins only.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+// --- EcoLogits-based energy/water constants ---
+// Source: https://ecologits.ai/latest/methodology/llm_inference/
+// GPU energy regression fitted to ML.ENERGY H100 benchmarks:
+//   gpu_energy_per_token (Wh) = α × e^(β × B) × P_active + γ
+const GPU_ENERGY_ALPHA = 1.1665e-6;
+const GPU_ENERGY_BETA = -0.01121;
+const GPU_ENERGY_GAMMA = 4.0529e-5;
+const BATCH_SIZE = 64;
+const GPU_MEMORY_GB = 80;
+const QUANTIZATION_BITS = 16;
+const SERVER_POWER_KW = 1.2;
+const SERVER_GPUS = 8;
+
+// Default Anthropic provider config (USA datacenter)
+const PUE = 1.11;
+const WUE_ONSITE = 0.56; // L/kWh
+const GRID_WUE_OFFSITE = 3.1321; // L/kWh
+
+// Default model: Claude Sonnet-class (MoE, ~440B total, ~88B active)
+const DEFAULT_TOTAL_PARAMS_B = 440;
+const DEFAULT_ACTIVE_PARAMS_B = 88;
+
+const PHONE_CHARGE_WH = 15.0;
+const ML_PER_SIP = 20.0;
+
+// --- Paths ---
+const CONFIG_DIR = path.join(os.homedir(), '.config', 'my-llm-footprint');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+const PENDING_PATH = path.join(CONFIG_DIR, 'pending.json');
+
+// ---------------------------------------------------------------------------
+// Transcript parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a JSONL transcript file and return an array of per-turn usage objects.
+ * Each object has: input, output, cache_create, cache_read, model.
+ *
+ * @param {string} filePath
+ * @returns {{ input: number, output: number, cache_create: number, cache_read: number, model: string }[]}
+ */
+function parseTranscript(filePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return [];
+  }
+
+  const turns = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    let entry;
+    try {
+      entry = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+
+    if (entry.type !== 'assistant') continue;
+
+    const msg = entry.message;
+    if (!msg || typeof msg !== 'object') continue;
+
+    const usage = msg.usage;
+    if (!usage) continue;
+
+    turns.push({
+      input: usage.input_tokens || 0,
+      output: usage.output_tokens || 0,
+      cache_create: usage.cache_creation_input_tokens || 0,
+      cache_read: usage.cache_read_input_tokens || 0,
+      model: msg.model || entry.model || 'unknown',
+    });
+  }
+
+  return turns;
+}
+
+// ---------------------------------------------------------------------------
+// Stats computation
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{ input: number, output: number, cache_create: number, cache_read: number, model: string }[]} turns
+ */
+function computeStats(turns) {
+  let totalInput = 0;
+  let totalOutput = 0;
+  let totalCacheCreate = 0;
+  let totalCacheRead = 0;
+
+  for (const t of turns) {
+    totalInput += t.input;
+    totalOutput += t.output;
+    totalCacheCreate += t.cache_create;
+    totalCacheRead += t.cache_read;
+  }
+
+  const last = turns.length > 0 ? turns[turns.length - 1] : null;
+
+  const lastInput = last ? last.input : 0;
+  const lastOutput = last ? last.output : 0;
+  const lastCacheCreate = last ? last.cache_create : 0;
+  const lastCacheRead = last ? last.cache_read : 0;
+
+  // For energy/water calcs use combined input (input + cache tokens)
+  const totalInAll = totalInput + totalCacheCreate + totalCacheRead;
+  const lastInAll = lastInput + lastCacheCreate + lastCacheRead;
+  const totalTokens = totalInAll + totalOutput;
+  const lastTokens = lastInAll + lastOutput;
+
+  // EcoLogits-based calculations
+  function gpuCount(totalParamsB) {
+    const memGB = 1.2 * totalParamsB * QUANTIZATION_BITS / 8;
+    const raw = Math.ceil(memGB / GPU_MEMORY_GB);
+    return Math.pow(2, Math.ceil(Math.log2(Math.max(raw, 1))));
+  }
+
+  function energy(inp, out) {
+    const gpus = gpuCount(DEFAULT_TOTAL_PARAMS_B);
+    const whPerToken = GPU_ENERGY_ALPHA * Math.exp(GPU_ENERGY_BETA * BATCH_SIZE) * DEFAULT_ACTIVE_PARAMS_B + GPU_ENERGY_GAMMA;
+    const gpuEnergy = out * (whPerToken / 1000); // kWh
+    const tps = DEFAULT_ACTIVE_PARAMS_B < 30 ? 80 : DEFAULT_ACTIVE_PARAMS_B < 100 ? 50 : 30;
+    const latency = out / tps;
+    const srvEnergy = (latency / 3600) * SERVER_POWER_KW * (gpus / SERVER_GPUS) * (1 / BATCH_SIZE);
+    return PUE * (srvEnergy + gpus * gpuEnergy) * 1000; // Wh
+  }
+
+  function water(tok, energyWh) {
+    const kwh = (energyWh !== undefined ? energyWh : energy(Math.round(tok * 0.8), tok - Math.round(tok * 0.8))) / 1000;
+    const liters = kwh * (WUE_ONSITE + PUE * GRID_WUE_OFFSITE);
+    return liters * 1000; // mL
+  }
+
+  return {
+    turns: turns.length,
+    model: last ? last.model : 'unknown',
+
+    // Raw delta (last turn) — for API payload
+    deltaInput: lastInput,
+    deltaOutput: lastOutput,
+    deltaCacheCreate: lastCacheCreate,
+    deltaCacheRead: lastCacheRead,
+
+    // Cumulative raw — for API payload
+    cumulativeIn: totalInput,
+    cumulativeOut: totalOutput,
+
+    // For display
+    totalTokens,
+    totalInAll,
+    totalOutput,
+    lastTokens,
+    lastInAll,
+    lastOutput,
+
+    energySessionWh: energy(totalInAll, totalOutput),
+    energyLastWh: energy(lastInAll, lastOutput),
+    waterSessionMl: water(totalTokens, energy(totalInAll, totalOutput)),
+    waterLastMl: water(lastTokens, energy(lastInAll, lastOutput)),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Stderr output
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {ReturnType<typeof computeStats>} s
+ */
+function formatOutput(s) {
+  if (s.turns === 0) return '';
+
+  const lines = [];
+
+  lines.push(
+    `Energy  ${s.energySessionWh.toFixed(4)} Wh session | ${s.energyLastWh.toFixed(4)} Wh last turn`,
+  );
+
+  lines.push(
+    `Water   ${s.waterSessionMl.toFixed(2)} mL session | ${s.waterLastMl.toFixed(2)} mL last turn`,
+  );
+
+  const turnWord = s.turns === 1 ? 'turn' : 'turns';
+  lines.push(
+    `Tokens  ${s.totalTokens.toLocaleString()} total ` +
+      `(${s.totalInAll.toLocaleString()} in / ${s.totalOutput.toLocaleString()} out) ` +
+      `over ${s.turns} ${turnWord}`,
+  );
+
+  const phonePct = (s.energySessionWh / PHONE_CHARGE_WH) * 100;
+  const sips = s.waterSessionMl / ML_PER_SIP;
+
+  const comparisons = [];
+  comparisons.push(phonePct < 0.01 ? '<0.01% of a phone charge' : `${phonePct.toFixed(2)}% of a phone charge`);
+  comparisons.push(sips < 0.1 ? '<0.1 sips of water' : `~${sips.toFixed(1)} sips of water`);
+
+  lines.push(`        = ${comparisons.join(' | ')}`);
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+/**
+ * @returns {{ apiKey: string, endpoint: string } | null}
+ */
+function readConfig() {
+  try {
+    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+    const cfg = JSON.parse(raw);
+    if (cfg && cfg.apiKey && cfg.endpoint) return cfg;
+  } catch {
+    // Config not yet installed or unreadable — silent skip
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Pending queue
+// ---------------------------------------------------------------------------
+
+/**
+ * @returns {object[]}
+ */
+function readPending() {
+  try {
+    const raw = fs.readFileSync(PENDING_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @param {object[]} queue
+ */
+function writePending(queue) {
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(PENDING_PATH, JSON.stringify(queue, null, 2));
+  } catch {
+    // Best-effort
+  }
+}
+
+// ---------------------------------------------------------------------------
+// API call
+// ---------------------------------------------------------------------------
+
+/**
+ * POST a single event payload to the API.
+ *
+ * @param {{ apiKey: string, endpoint: string }} config
+ * @param {object} payload
+ * @returns {Promise<void>} Resolves on 2xx, rejects otherwise.
+ */
+async function postEvent(config, payload) {
+  const url = `${config.endpoint.replace(/\/$/, '')}/api/v1/ingest/events`;
+
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${config.apiKey}`,
+    },
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(10000),
+  });
+
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status}: ${await res.text()}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Flush pending queue
+// ---------------------------------------------------------------------------
+
+/**
+ * Attempt to flush all pending events. Silently stops on first failure.
+ *
+ * @param {{ apiKey: string, endpoint: string }} config
+ */
+async function flushPending(config) {
+  const queue = readPending();
+  if (queue.length === 0) return;
+
+  const remaining = [];
+  for (const event of queue) {
+    try {
+      await postEvent(config, event);
+    } catch {
+      // Keep this and all subsequent events for next time
+      remaining.push(event);
+      break;
+    }
+  }
+
+  // If we drained everything, remove the file; otherwise write what's left
+  if (remaining.length === 0) {
+    try {
+      fs.unlinkSync(PENDING_PATH);
+    } catch {
+      writePending([]);
+    }
+  } else {
+    // Find where we stopped and preserve the rest
+    const failedIdx = queue.indexOf(remaining[0]);
+    writePending(failedIdx >= 0 ? queue.slice(failedIdx) : queue);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  // 1. Read stdin
+  let stdinData = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) {
+    stdinData += chunk;
+  }
+
+  let event;
+  try {
+    event = JSON.parse(stdinData);
+  } catch {
+    // Malformed input — nothing to do
+    process.exit(0);
+  }
+
+  const transcriptPath = event.transcript_path || '';
+  const sessionId = event.session_id || 'unknown';
+
+  // 2. Parse transcript
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+    process.exit(0);
+  }
+
+  const turns = parseTranscript(transcriptPath);
+
+  // 3. Print energy/water summary to stderr (even without config)
+  if (turns.length > 0) {
+    const stats = computeStats(turns);
+    const output = formatOutput(stats);
+    if (output) {
+      process.stderr.write(`\n${output}\n`);
+    }
+
+    // 4. Read API config
+    const config = readConfig();
+    if (!config) {
+      // No config installed yet — just display the summary and exit
+      process.exit(0);
+    }
+
+    // 5. Build payload
+    const payload = {
+      session_id: sessionId,
+      provider: 'anthropic',
+      model: stats.model,
+      input_tokens: stats.deltaInput,
+      output_tokens: stats.deltaOutput,
+      cache_create: stats.deltaCacheCreate,
+      cache_read: stats.deltaCacheRead,
+      cumulative_in: stats.cumulativeIn,
+      cumulative_out: stats.cumulativeOut,
+      turn_number: stats.turns,
+    };
+
+    // 6. POST to API
+    try {
+      await postEvent(config, payload);
+      // 7. On success: flush pending queue
+      await flushPending(config);
+    } catch {
+      // 6a. On failure: queue the event
+      const queue = readPending();
+      queue.push(payload);
+      writePending(queue);
+    }
+  }
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "my-llm-footprint",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "my-llm-footprint": "./bin/init.js"
+  },
+  "files": ["bin", "hooks"],
+  "engines": { "node": ">=18" }
+}