@diogonzafe/tokenwatch 0.4.0 → 0.6.0

package/dist/cli.js

@@ -245,7 +245,7 @@ function maybeSuggestCheaperModel(model, costUSD, inputTokens, outputTokens, lay
 
 // prices.json
 var prices_default = {
-  updated_at: "2026-04-22",
+  updated_at: "2026-04-23",
   source: "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json",
   models: {
     "gpt-4o": {
@@ -1594,7 +1594,14 @@ var TrackerConfigSchema = z.object({
     perUser: BudgetConfigSchema.optional(),
     perSession: BudgetConfigSchema.optional()
   }).optional(),
-  suggestions: z.boolean().optional().default(false)
+  suggestions: z.boolean().optional().default(false),
+  anomalyDetection: z.object({
+    multiplierThreshold: z.number().positive(),
+    webhookUrl: z.string().url(),
+    windowHours: z.number().positive().optional().default(24),
+    mode: z.enum(["once", "always"]).optional().default("once")
+  }).optional(),
+  exporter: z.custom((v) => v !== null && typeof v === "object" && typeof v.export === "function").optional()
 });
 function createTracker(config = {}) {
   const parsed = TrackerConfigSchema.safeParse(config);
@@ -1611,7 +1618,9 @@ ${issues}`);
     customPrices,
     warnIfStaleAfterHours,
     budgets,
-    suggestions
+    suggestions,
+    anomalyDetection,
+    exporter
   } = parsed.data;
   const storage = typeof storageOption === "object" ? storageOption : createStorage(storageOption);
   let remotePrices;
@@ -1644,6 +1653,7 @@ ${issues}`);
   let alertFired = false;
   const firedUserAlerts = /* @__PURE__ */ new Set();
   const firedSessionAlerts = /* @__PURE__ */ new Set();
+  const firedAnomalyKeys = /* @__PURE__ */ new Set();
   const startedAt = (/* @__PURE__ */ new Date()).toISOString();
   function resolveModelPrice(model) {
     maybeWarnStaleness();
@@ -1668,7 +1678,12 @@ ${issues}`);
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     };
     storage.record(full);
+    if (exporter) {
+      Promise.resolve(exporter.export(full)).catch(() => {
+      });
+    }
     maybeFireAlerts(full);
+    if (anomalyDetection) maybeDetectAnomaly(full);
     if (suggestions) {
       maybeSuggestCheaperModel(entry.model, costUSD, entry.inputTokens, entry.outputTokens, {
         bundledPrices,
@@ -1838,11 +1853,56 @@ ${issues}`);
       basedOnPeriod: { from: first, to: last }
     };
   }
+  function maybeDetectAnomaly(entry) {
+    if (entry.costUSD <= 0) return;
+    const { multiplierThreshold, webhookUrl: aUrl, windowHours: wh, mode: modeRaw } = anomalyDetection;
+    const wHours = wh ?? 24;
+    const mode = modeRaw ?? "once";
+    const windowStart = Date.now() - wHours * 60 * 60 * 1e3;
+    const entryTs = new Date(entry.timestamp).getTime();
+    function checkEntity(key, label, predicate) {
+      if (mode !== "always" && firedAnomalyKeys.has(key)) return;
+      if (mode !== "always") firedAnomalyKeys.add(key);
+      Promise.resolve(storage.getAll()).then((all) => {
+        const history = all.filter(
+          (e) => predicate(e) && new Date(e.timestamp).getTime() >= windowStart && new Date(e.timestamp).getTime() !== entryTs
+        );
+        if (history.length === 0) {
+          if (mode !== "always") firedAnomalyKeys.delete(key);
+          return;
+        }
+        const avg = history.reduce((s, e) => s + e.costUSD, 0) / history.length;
+        if (avg <= 0 || entry.costUSD <= avg * multiplierThreshold) {
+          if (mode !== "always") firedAnomalyKeys.delete(key);
+          return;
+        }
+        const multiple = (entry.costUSD / avg).toFixed(1);
+        fireWebhook(aUrl, {
+          text: `[tokenwatch] Anomaly: ${label} call cost $${entry.costUSD.toFixed(4)} is ${multiple}x above ${wHours}h average ($${avg.toFixed(4)})`
+        });
+      }).catch(() => {
+        if (mode !== "always") firedAnomalyKeys.delete(key);
+      });
+    }
+    if (entry.userId) {
+      checkEntity(
+        `user:${entry.userId}`,
+        `user "${entry.userId}"`,
+        (e) => e.userId === entry.userId
+      );
+    }
+    checkEntity(
+      `model:${entry.model}`,
+      `model "${entry.model}"`,
+      (e) => e.model === entry.model
+    );
+  }
   async function reset() {
     await Promise.resolve(storage.clearAll());
     alertFired = false;
     firedUserAlerts.clear();
     firedSessionAlerts.clear();
+    firedAnomalyKeys.clear();
   }
   async function resetSession(sessionId) {
     await Promise.resolve(storage.clearSession(sessionId));
@@ -1926,6 +1986,764 @@ function csvEscape(value) {
   return value;
 }
 
+// src/dashboard/server.ts
+import { createServer } from "http";
+
+// src/dashboard/data.ts
+function parseSince(filter) {
+  if (!filter || filter === "all") return void 0;
+  const now = Date.now();
+  switch (filter) {
+    case "1h":
+      return now - 60 * 60 * 1e3;
+    case "24h":
+      return now - 24 * 60 * 60 * 1e3;
+    case "7d":
+      return now - 7 * 24 * 60 * 60 * 1e3;
+    case "30d":
+      return now - 30 * 24 * 60 * 60 * 1e3;
+    default:
+      return void 0;
+  }
+}
+function buildTimeSeries(entries, sinceMs) {
+  const now = Date.now();
+  const windowMs = sinceMs !== void 0 ? now - sinceMs : void 0;
+  let bucketMs;
+  if (windowMs !== void 0 && windowMs <= 60 * 60 * 1e3) {
+    bucketMs = 5 * 60 * 1e3;
+  } else if (windowMs !== void 0 && windowMs <= 24 * 60 * 60 * 1e3) {
+    bucketMs = 60 * 60 * 1e3;
+  } else {
+    bucketMs = 24 * 60 * 60 * 1e3;
+  }
+  const filtered = sinceMs !== void 0 ? entries.filter((e) => new Date(e.timestamp).getTime() >= sinceMs) : entries;
+  const buckets = /* @__PURE__ */ new Map();
+  for (const entry of filtered) {
+    const ts = new Date(entry.timestamp).getTime();
+    const bucketTs = Math.floor(ts / bucketMs) * bucketMs;
+    const bucketKey = new Date(bucketTs).toISOString();
+    const existing = buckets.get(bucketKey);
+    if (existing) {
+      existing.cost += entry.costUSD;
+      existing.calls += 1;
+    } else {
+      buckets.set(bucketKey, { bucket: bucketKey, cost: entry.costUSD, calls: 1 });
+    }
+  }
+  return Array.from(buckets.values()).sort((a, b) => a.bucket.localeCompare(b.bucket));
+}
+function getFingerprint(data) {
+  return `${data.report.totalCostUSD.toFixed(8)}-${data.report.totalTokens.input}-${data.timeSeries.length}`;
+}
+async function getDashboardData(storage, filter) {
+  const allEntries = await Promise.resolve(storage.getAll());
+  const sinceMs = parseSince(filter);
+  const entries = sinceMs !== void 0 ? allEntries.filter((e) => new Date(e.timestamp).getTime() >= sinceMs) : allEntries;
+  const byModel = {};
+  const bySession = {};
+  const byUser = {};
+  const byFeature = {};
+  let totalInput = 0;
+  let totalOutput = 0;
+  let totalCost = 0;
+  for (const e of entries) {
+    totalInput += e.inputTokens + (e.cachedTokens ?? 0) + (e.cacheCreationTokens ?? 0);
+    totalOutput += e.outputTokens;
+    totalCost += e.costUSD;
+    const m = byModel[e.model] ??= {
+      costUSD: 0,
+      calls: 0,
+      tokens: { input: 0, output: 0, reasoning: 0, cached: 0 }
+    };
+    m.costUSD += e.costUSD;
+    m.calls += 1;
+    m.tokens.input += e.inputTokens + (e.cachedTokens ?? 0) + (e.cacheCreationTokens ?? 0);
+    m.tokens.output += e.outputTokens;
+    m.tokens.reasoning += e.reasoningTokens ?? 0;
+    m.tokens.cached += e.cachedTokens ?? 0;
+    if (e.sessionId) {
+      const s = bySession[e.sessionId] ??= { costUSD: 0, calls: 0 };
+      s.costUSD += e.costUSD;
+      s.calls += 1;
+    }
+    if (e.userId) {
+      const u = byUser[e.userId] ??= { costUSD: 0, calls: 0 };
+      u.costUSD += e.costUSD;
+      u.calls += 1;
+    }
+    if (e.feature) {
+      const f = byFeature[e.feature] ??= { costUSD: 0, calls: 0 };
+      f.costUSD += e.costUSD;
+      f.calls += 1;
+    }
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const periodFrom = entries[0]?.timestamp ?? now;
+  const periodTo = entries[entries.length - 1]?.timestamp ?? now;
+  const report = {
+    totalCostUSD: totalCost,
+    totalTokens: { input: totalInput, output: totalOutput },
+    byModel,
+    bySession,
+    byUser,
+    byFeature,
+    period: { from: periodFrom, to: periodTo }
+  };
+  const forecastWindowMs = 24 * 60 * 60 * 1e3;
+  const windowStart = Date.now() - forecastWindowMs;
+  const windowEntries = allEntries.filter(
+    (e) => new Date(e.timestamp).getTime() >= windowStart
+  );
+  let forecast;
+  if (windowEntries.length < 2) {
+    forecast = {
+      burnRatePerHour: 0,
+      projectedDailyCostUSD: 0,
+      projectedMonthlyCostUSD: 0,
+      basedOnHours: 0,
+      basedOnPeriod: null
+    };
+  } else {
+    const first = windowEntries[0]?.timestamp ?? "";
+    const last = windowEntries[windowEntries.length - 1]?.timestamp ?? "";
+    const actualMs = new Date(last).getTime() - new Date(first).getTime();
+    const actualHours = actualMs / (1e3 * 60 * 60);
+    if (actualHours < 1e-3) {
+      forecast = {
+        burnRatePerHour: 0,
+        projectedDailyCostUSD: 0,
+        projectedMonthlyCostUSD: 0,
+        basedOnHours: 0,
+        basedOnPeriod: { from: first, to: last }
+      };
+    } else {
+      const windowCost = windowEntries.reduce((s, e) => s + e.costUSD, 0);
+      const burnRatePerHour = windowCost / actualHours;
+      forecast = {
+        burnRatePerHour,
+        projectedDailyCostUSD: burnRatePerHour * 24,
+        projectedMonthlyCostUSD: burnRatePerHour * 24 * 30,
+        basedOnHours: Math.round(actualHours * 100) / 100,
+        basedOnPeriod: { from: first, to: last }
+      };
+    }
+  }
+  const timeSeries = buildTimeSeries(allEntries, sinceMs);
+  return { report, forecast, timeSeries, lastUpdated: now };
+}
+
+// src/dashboard/html.ts
+function getHtml(port) {
+  void port;
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>tokenwatch dashboard</title>
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js"></script>
+<style>
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+:root {
+  --bg:      #0d1117;
+  --surface: #161b22;
+  --border:  #30363d;
+  --text:    #e6edf3;
+  --muted:   #8b949e;
+  --accent:  #58a6ff;
+  --green:   #3fb950;
+  --yellow:  #d29922;
+  --red:     #f85149;
+  --r:       6px;
+}
+
+body {
+  background: var(--bg);
+  color: var(--text);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  font-size: 14px;
+  line-height: 1.5;
+  min-height: 100vh;
+}
+
+.container { max-width: 1200px; margin: 0 auto; padding: 24px 16px; }
+
+/* \u2500\u2500 Header \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 24px;
+}
+header h1 { font-size: 18px; font-weight: 600; letter-spacing: -0.3px; }
+header h1 span { color: var(--accent); }
+
+.live-badge {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 12px;
+  color: var(--muted);
+}
+.live-dot {
+  width: 8px; height: 8px;
+  border-radius: 50%;
+  background: var(--green);
+  animation: pulse 2s ease-in-out infinite;
+}
+@keyframes pulse {
+  0%, 100% { opacity: 1; }
+  50%       { opacity: 0.3; }
+}
+
+/* \u2500\u2500 Tabs \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+.tabs {
+  display: flex;
+  gap: 4px;
+  margin-bottom: 24px;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--r);
+  padding: 4px;
+  width: fit-content;
+}
+.tab {
+  padding: 6px 14px;
+  border-radius: calc(var(--r) - 2px);
+  border: none;
+  background: transparent;
+  color: var(--muted);
+  font-size: 13px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background 0.15s, color 0.15s;
+}
+.tab:hover { color: var(--text); background: rgba(255,255,255,0.05); }
+.tab.active { background: var(--accent); color: #fff; }
+
+/* \u2500\u2500 Overview cards \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+.cards {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+  gap: 12px;
+  margin-bottom: 24px;
+}
+.card {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--r);
+  padding: 16px;
+}
+.card-label { font-size: 11px; text-transform: uppercase; letter-spacing: 0.5px; color: var(--muted); margin-bottom: 6px; }
+.card-value { font-size: 22px; font-weight: 700; color: var(--text); font-variant-numeric: tabular-nums; }
+.card-sub { font-size: 11px; color: var(--muted); margin-top: 3px; }
+
+/* \u2500\u2500 Chart section \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+.charts {
+  display: grid;
+  grid-template-columns: 2fr 1fr;
+  gap: 16px;
+  margin-bottom: 24px;
+}
+@media (max-width: 768px) { .charts { grid-template-columns: 1fr; } }
+
+.panel {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--r);
+  padding: 16px;
+}
+.panel-title {
+  font-size: 12px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  color: var(--muted);
+  margin-bottom: 14px;
+}
+.chart-wrap { position: relative; height: 220px; }
+
+/* \u2500\u2500 Breakdown tables \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+.section { margin-bottom: 24px; }
+.section-title {
+  font-size: 12px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  color: var(--muted);
+  margin-bottom: 10px;
+}
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--r);
+  overflow: hidden;
+  font-size: 13px;
+}
+thead { background: rgba(255,255,255,0.03); }
+th {
+  padding: 10px 14px;
+  text-align: left;
+  font-weight: 600;
+  color: var(--muted);
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.4px;
+  border-bottom: 1px solid var(--border);
+}
+th.num, td.num { text-align: right; }
+td {
+  padding: 10px 14px;
+  border-bottom: 1px solid rgba(48,54,61,0.5);
+  font-variant-numeric: tabular-nums;
+  color: var(--text);
+}
+tbody tr:last-child td { border-bottom: none; }
+tbody tr:hover td { background: rgba(255,255,255,0.02); }
+
+.bar-wrap { width: 80px; height: 6px; background: var(--border); border-radius: 3px; display: inline-block; vertical-align: middle; margin-left: 8px; }
+.bar-fill { height: 100%; border-radius: 3px; background: var(--accent); }
+
+/* \u2500\u2500 Forecast \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+.forecast-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+  gap: 12px;
+}
+
+/* \u2500\u2500 Empty state \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+.empty {
+  color: var(--muted);
+  font-size: 13px;
+  padding: 20px 0;
+  text-align: center;
+}
+
+/* \u2500\u2500 Collapsible \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+details summary {
+  cursor: pointer;
+  list-style: none;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 12px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  color: var(--muted);
+  margin-bottom: 10px;
+  user-select: none;
+}
+details summary::before { content: '\u25B6'; font-size: 10px; transition: transform 0.15s; }
+details[open] summary::before { transform: rotate(90deg); }
+
+/* \u2500\u2500 Last updated \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
+.footer {
+  font-size: 11px;
+  color: var(--muted);
+  text-align: center;
+  padding: 16px 0 0;
+}
+</style>
+</head>
+<body>
+<div class="container">
+
+  <header>
+    <h1>token<span>watch</span></h1>
+    <div class="live-badge">
+      <div class="live-dot"></div>
+      <span id="live-label">live</span>
+    </div>
+  </header>
+
+  <div class="tabs">
+    <button class="tab" data-filter="1h">1h</button>
+    <button class="tab active" data-filter="24h">24h</button>
+    <button class="tab" data-filter="7d">7d</button>
+    <button class="tab" data-filter="30d">30d</button>
+    <button class="tab" data-filter="all">All</button>
+  </div>
+
+  <div class="cards">
+    <div class="card">
+      <div class="card-label">Total Cost</div>
+      <div class="card-value" id="card-cost">\u2014</div>
+      <div class="card-sub" id="card-period"></div>
+    </div>
+    <div class="card">
+      <div class="card-label">Input Tokens</div>
+      <div class="card-value" id="card-input">\u2014</div>
+    </div>
+    <div class="card">
+      <div class="card-label">Output Tokens</div>
+      <div class="card-value" id="card-output">\u2014</div>
+    </div>
+    <div class="card">
+      <div class="card-label">Total Calls</div>
+      <div class="card-value" id="card-calls">\u2014</div>
+    </div>
+    <div class="card">
+      <div class="card-label">Burn Rate</div>
+      <div class="card-value" id="card-burn">\u2014</div>
+      <div class="card-sub">per hour</div>
+    </div>
+  </div>
+
+  <div class="charts">
+    <div class="panel">
+      <div class="panel-title">Cost over time</div>
+      <div class="chart-wrap">
+        <canvas id="chart-line"></canvas>
+      </div>
+    </div>
+    <div class="panel">
+      <div class="panel-title">By model</div>
+      <div class="chart-wrap">
+        <canvas id="chart-doughnut"></canvas>
+      </div>
+    </div>
+  </div>
+
+  <div class="section">
+    <div class="section-title">Model breakdown</div>
+    <div id="model-table-wrap"></div>
+  </div>
+
+  <details id="users-section" style="margin-bottom:24px;">
+    <summary>By user</summary>
+    <div id="user-table-wrap"></div>
+  </details>
+
+  <details id="features-section" style="margin-bottom:24px;">
+    <summary>By feature</summary>
+    <div id="feature-table-wrap"></div>
+  </details>
+
+  <div class="section">
+    <div class="section-title">Cost forecast</div>
+    <div class="forecast-grid">
+      <div class="card">
+        <div class="card-label">Projected daily</div>
+        <div class="card-value" id="fc-daily">\u2014</div>
+        <div class="card-sub" id="fc-window"></div>
+      </div>
+      <div class="card">
+        <div class="card-label">Projected monthly</div>
+        <div class="card-value" id="fc-monthly">\u2014</div>
+      </div>
+      <div class="card">
+        <div class="card-label">Burn rate / hr</div>
+        <div class="card-value" id="fc-burn">\u2014</div>
+      </div>
+    </div>
+  </div>
+
+  <div class="footer" id="footer-updated"></div>
+
+</div><!-- /container -->
+
+<script>
+(function () {
+  'use strict';
+
+  // \u2500\u2500 Palette \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  const PALETTE = [
+    '#58a6ff','#3fb950','#f78166','#d29922','#bc8cff',
+    '#79c0ff','#56d364','#ffa657','#ff7b72','#a5d6ff',
+  ];
+
+  // \u2500\u2500 State \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  let evtSource = null;
+  let activeFilter = '24h';
+  let lineChart = null;
+  let doughnutChart = null;
+
+  // \u2500\u2500 Helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  function escHtml(str) {
+    return String(str)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+  }
+
+  function fmtUSD(n) {
+    if (n === 0) return '$0.00';
+    if (n < 0.001) return '$' + n.toFixed(6);
+    if (n < 1)     return '$' + n.toFixed(4);
+    return '$' + n.toFixed(2);
+  }
+
+  function fmtNum(n) {
+    return n.toLocaleString('en-US');
+  }
+
+  function fmtDate(iso) {
+    try { return new Date(iso).toLocaleString(); } catch { return iso; }
+  }
+
+  function totalCalls(byModel) {
+    return Object.values(byModel).reduce(function(s, m) { return s + m.calls; }, 0);
+  }
+
+  // \u2500\u2500 Tab setup \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  document.querySelectorAll('.tab').forEach(function(btn) {
+    btn.addEventListener('click', function() {
+      document.querySelectorAll('.tab').forEach(function(b) { b.classList.remove('active'); });
+      btn.classList.add('active');
+      activeFilter = btn.dataset.filter;
+      reconnect();
+    });
+  });
+
+  // \u2500\u2500 SSE \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  function reconnect() {
+    if (evtSource) { evtSource.close(); evtSource = null; }
+    evtSource = new EventSource('/events?filter=' + encodeURIComponent(activeFilter));
+    evtSource.onmessage = function(e) {
+      try { updateUI(JSON.parse(e.data)); } catch (_) {}
+    };
+    evtSource.onerror = function() {
+      document.getElementById('live-label').textContent = 'reconnecting\u2026';
+    };
+    evtSource.onopen = function() {
+      document.getElementById('live-label').textContent = 'live';
+    };
+  }
+
+  // \u2500\u2500 UI update \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  function updateUI(data) {
+    const r = data.report;
+    const fc = data.forecast;
+    const ts = data.timeSeries;
+
+    // Cards
+    document.getElementById('card-cost').textContent = fmtUSD(r.totalCostUSD);
+    document.getElementById('card-input').textContent = fmtNum(r.totalTokens.input);
+    document.getElementById('card-output').textContent = fmtNum(r.totalTokens.output);
+    document.getElementById('card-calls').textContent = fmtNum(totalCalls(r.byModel));
+    document.getElementById('card-burn').textContent = fmtUSD(fc.burnRatePerHour);
+    document.getElementById('card-period').textContent =
+      r.period.from !== r.period.to
+        ? fmtDate(r.period.from) + ' \u2013 ' + fmtDate(r.period.to)
+        : '';
+
+    // Line chart
+    const labels = ts.map(function(b) {
+      try { return new Date(b.bucket).toLocaleTimeString([], {hour:'2-digit', minute:'2-digit'}); }
+      catch { return b.bucket; }
+    });
+    const costs = ts.map(function(b) { return b.cost; });
+
+    if (!lineChart) {
+      const ctx = document.getElementById('chart-line').getContext('2d');
+      lineChart = new Chart(ctx, {
+        type: 'line',
+        data: {
+          labels: labels,
+          datasets: [{
+            label: 'Cost (USD)',
+            data: costs,
+            borderColor: '#58a6ff',
+            backgroundColor: 'rgba(88,166,255,0.08)',
+            borderWidth: 2,
+            pointRadius: 3,
+            pointBackgroundColor: '#58a6ff',
+            fill: true,
+            tension: 0.3,
+          }],
+        },
+        options: {
+          responsive: true, maintainAspectRatio: false,
+          plugins: { legend: { display: false } },
+          scales: {
+            x: { ticks: { color: '#8b949e', maxTicksLimit: 8 }, grid: { color: '#21262d' } },
+            y: {
+              ticks: {
+                color: '#8b949e',
+                callback: function(v) { return '$' + Number(v).toFixed(4); },
+              },
+              grid: { color: '#21262d' },
+            },
+          },
+        },
+      });
+    } else {
+      lineChart.data.labels = labels;
+      lineChart.data.datasets[0].data = costs;
+      lineChart.update('none');
+    }
+
+    // Doughnut chart
+    const modelEntries = Object.entries(r.byModel);
+    const dLabels = modelEntries.map(function(x) { return x[0]; });
+    const dData = modelEntries.map(function(x) { return x[1].costUSD; });
+    const dColors = dLabels.map(function(_, i) { return PALETTE[i % PALETTE.length]; });
+
+    if (!doughnutChart) {
+      const ctx2 = document.getElementById('chart-doughnut').getContext('2d');
+      doughnutChart = new Chart(ctx2, {
+        type: 'doughnut',
+        data: { labels: dLabels, datasets: [{ data: dData, backgroundColor: dColors, borderWidth: 0, hoverOffset: 4 }] },
+        options: {
+          responsive: true, maintainAspectRatio: false,
+          cutout: '65%',
+          plugins: {
+            legend: {
+              position: 'bottom',
+              labels: { color: '#8b949e', boxWidth: 10, padding: 12, font: { size: 11 } },
+            },
+          },
+        },
+      });
+    } else {
+      doughnutChart.data.labels = dLabels;
+      doughnutChart.data.datasets[0].data = dData;
+      doughnutChart.data.datasets[0].backgroundColor = dColors;
+      doughnutChart.update('none');
+    }
+
+    // Model table
+    const modelWrap = document.getElementById('model-table-wrap');
+    if (modelEntries.length === 0) {
+      modelWrap.innerHTML = '<p class="empty">No data for this period.</p>';
+    } else {
+      const totalCost = r.totalCostUSD || 1;
+      let html = '<table><thead><tr>' +
+        '<th>Model</th>' +
+        '<th class="num">Calls</th>' +
+        '<th class="num">In tokens</th>' +
+        '<th class="num">Out tokens</th>' +
+        '<th class="num">Cost</th>' +
+        '<th class="num">Share</th>' +
+        '</tr></thead><tbody>';
+      const sorted = modelEntries.slice().sort(function(a, b) { return b[1].costUSD - a[1].costUSD; });
+      sorted.forEach(function(entry) {
+        const name = entry[0]; const m = entry[1];
+        const pct = (m.costUSD / totalCost * 100).toFixed(1);
+        const barW = Math.round(m.costUSD / totalCost * 80);
+        html += '<tr>' +
+          '<td>' + escHtml(name) + '</td>' +
+          '<td class="num">' + fmtNum(m.calls) + '</td>' +
+          '<td class="num">' + fmtNum(m.tokens.input) + '</td>' +
+          '<td class="num">' + fmtNum(m.tokens.output) + '</td>' +
+          '<td class="num">' + fmtUSD(m.costUSD) + '</td>' +
+          '<td class="num">' + pct + '%' +
+          '<span class="bar-wrap"><span class="bar-fill" style="width:' + barW + 'px"></span></span>' +
+          '</td></tr>';
+      });
+      html += '</tbody></table>';
+      modelWrap.innerHTML = html;
+    }
+
+    // User table
+    const userEntries = Object.entries(r.byUser);
+    const usersSection = document.getElementById('users-section');
+    usersSection.style.display = userEntries.length === 0 ? 'none' : '';
+    if (userEntries.length > 0) {
+      let html = '<table><thead><tr><th>User</th><th class="num">Calls</th><th class="num">Cost</th></tr></thead><tbody>';
+      userEntries.slice().sort(function(a,b) { return b[1].costUSD - a[1].costUSD; }).forEach(function(e) {
+        html += '<tr><td>' + escHtml(e[0]) + '</td><td class="num">' + fmtNum(e[1].calls) + '</td><td class="num">' + fmtUSD(e[1].costUSD) + '</td></tr>';
+      });
+      html += '</tbody></table>';
+      document.getElementById('user-table-wrap').innerHTML = html;
+    }
+
+    // Feature table
+    const featureEntries = Object.entries(r.byFeature);
+    const featuresSection = document.getElementById('features-section');
+    featuresSection.style.display = featureEntries.length === 0 ? 'none' : '';
+    if (featureEntries.length > 0) {
+      let html = '<table><thead><tr><th>Feature</th><th class="num">Calls</th><th class="num">Cost</th></tr></thead><tbody>';
+      featureEntries.slice().sort(function(a,b) { return b[1].costUSD - a[1].costUSD; }).forEach(function(e) {
+        html += '<tr><td>' + escHtml(e[0]) + '</td><td class="num">' + fmtNum(e[1].calls) + '</td><td class="num">' + fmtUSD(e[1].costUSD) + '</td></tr>';
+      });
+      html += '</tbody></table>';
+      document.getElementById('feature-table-wrap').innerHTML = html;
+    }
+
+    // Forecast
+    document.getElementById('fc-daily').textContent = fmtUSD(fc.projectedDailyCostUSD);
+    document.getElementById('fc-monthly').textContent = fmtUSD(fc.projectedMonthlyCostUSD);
+    document.getElementById('fc-burn').textContent = fmtUSD(fc.burnRatePerHour);
+    document.getElementById('fc-window').textContent =
+      fc.basedOnHours > 0 ? 'based on ' + fc.basedOnHours.toFixed(1) + 'h of data' : 'insufficient data';
+
+    // Footer
+    document.getElementById('footer-updated').textContent =
+      'Last updated: ' + fmtDate(data.lastUpdated);
+  }
+
+  // \u2500\u2500 Boot \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  reconnect();
+})();
+</script>
+</body>
+</html>`;
+}
+
+// src/dashboard/server.ts
+function startDashboardServer(storage, port) {
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", `http://localhost:${port}`);
+    if (req.method === "GET" && url.pathname === "/") {
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(getHtml(port));
+      return;
+    }
+    if (req.method === "GET" && url.pathname === "/events") {
+      const filter = url.searchParams.get("filter") ?? "24h";
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+        "X-Accel-Buffering": "no"
+      });
+      res.flushHeaders();
+      let lastFingerprint = "";
+      async function sendData() {
+        try {
+          const data = await getDashboardData(storage, filter);
+          const fp = getFingerprint(data);
+          if (fp !== lastFingerprint) {
+            lastFingerprint = fp;
+            res.write(`data: ${JSON.stringify(data)}
+
+`);
+          }
+        } catch {
+        }
+      }
+      void sendData();
+      const timer = setInterval(() => {
+        void sendData();
+      }, 3e3);
+      res.on("close", () => {
+        clearInterval(timer);
+      });
+      return;
+    }
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not found");
+  });
+  server.on("error", (err) => {
+    if (err.code === "EADDRINUSE") {
+      console.error(`[tokenwatch] Port ${port} is already in use. Try: tokenwatch dashboard --port <other>`);
+      process.exit(1);
+    }
+    throw err;
+  });
+  server.listen(port, () => {
+    console.log(`tokenwatch dashboard \u2192 http://localhost:${port}`);
+  });
+}
+
 // bin/cli.ts
 var __dirname = dirname(fileURLToPath(import.meta.url));
 var DB_PATH2 = join3(homedir3(), ".tokenwatch", "usage.db");
@@ -2014,20 +2832,36 @@ async function cmdReport() {
   }
   console.log("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
 }
+async function cmdDashboard(port) {
+  if (!existsSync2(DB_PATH2)) {
+    console.log(`No SQLite database found at ${DB_PATH2}`);
+    console.log("Start your app with storage: 'sqlite' to begin recording usage.");
+    process.exit(1);
+  }
+  let storage;
+  try {
+    storage = new SqliteStorage(DB_PATH2);
+  } catch {
+    console.error("Failed to open SQLite database. Is better-sqlite3 installed?");
+    console.error("Run: npm install better-sqlite3");
+    process.exit(1);
+  }
+  startDashboardServer(storage, port);
+}
 function cmdHelp() {
   console.log(`
 tokenwatch \u2014 CLI
 
 Commands:
-  sync      Fetch and cache latest model prices from remote
-  prices    List all bundled models and their current prices
-  report    Show last saved usage report (requires SQLite storage)
-  help      Show this help message
+  sync                  Fetch and cache latest model prices from remote
+  prices                List all bundled models and their current prices
+  report                Show last saved usage report (requires SQLite storage)
+  dashboard [--port N]  Open local web dashboard (default port: 4242)
+  help                  Show this help message
 `.trim());
 }
 async function main() {
   const [, , cmd, ...args] = process.argv;
-  void args;
   switch (cmd) {
     case "sync":
       await cmdSync();
@@ -2038,6 +2872,12 @@ async function main() {
     case "report":
       await cmdReport();
       break;
+    case "dashboard": {
+      const portFlagIdx = args.indexOf("--port");
+      const port = portFlagIdx !== -1 ? parseInt(args[portFlagIdx + 1] ?? "4242", 10) : 4242;
+      await cmdDashboard(port);
+      break;
+    }
     case "help":
     case void 0:
       cmdHelp();