feat(ui): add usage analytics dashboard with time-series charts

Add a new Analytics tab to the Control UI that displays:
- Summary stats: total tokens, input/output, cache read/write, estimated cost
- Daily token usage bar chart
- Daily cost bar chart
- Configurable time period (7/14/30/90 days)

Uses existing usage.cost gateway endpoint which returns daily aggregated
data from session transcripts.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

ui/src/ui/app-render.ts

@@ -50,6 +50,7 @@ import {
   rotateDeviceToken,
 } from "./controllers/devices";
 import { renderSkills } from "./views/skills";
+import { renderAnalytics } from "./views/analytics";
 import { renderChatControls, renderTab, renderThemeToggle } from "./app-render.helpers";
 import { loadChannels } from "./controllers/channels";
 import { loadPresence } from "./controllers/presence";
@@ -81,6 +82,7 @@ import {
 import { loadCronRuns, toggleCronJob, runCronJob, removeCronJob, addCronJob } from "./controllers/cron";
 import { loadDebug, callDebugMethod } from "./controllers/debug";
 import { loadLogs } from "./controllers/logs";
+import { loadAnalytics } from "./controllers/analytics";
 
 const AVATAR_DATA_RE = /^data:/i;
 const AVATAR_HTTP_RE = /^https?:\/\//i;
@@ -304,6 +306,20 @@ export function renderApp(state: AppViewState) {
 	            })
 	          : nothing}
 
+        ${state.tab === "analytics"
+          ? renderAnalytics({
+              loading: state.analyticsLoading,
+              error: state.analyticsError,
+              data: state.analyticsData,
+              days: state.analyticsDays,
+              onDaysChange: (days) => {
+                state.analyticsDays = days;
+                void loadAnalytics(state);
+              },
+              onRefresh: () => loadAnalytics(state),
+            })
+          : nothing}
+
         ${state.tab === "cron"
           ? renderCron({
               loading: state.cronLoading,

ui/src/ui/app-settings.ts

@@ -1,3 +1,4 @@
+import { loadAnalytics } from "./controllers/analytics";
 import { loadConfig, loadConfigSchema } from "./controllers/config";
 import { loadCronJobs, loadCronStatus } from "./controllers/cron";
 import { loadChannels } from "./controllers/channels";
@@ -146,6 +147,7 @@ export async function refreshActiveTab(host: SettingsHost) {
   if (host.tab === "channels") await loadChannelsTab(host);
   if (host.tab === "instances") await loadPresence(host as unknown as ClawdbotApp);
   if (host.tab === "sessions") await loadSessions(host as unknown as ClawdbotApp);
+  if (host.tab === "analytics") await loadAnalytics(host as unknown as ClawdbotApp);
   if (host.tab === "cron") await loadCron(host);
   if (host.tab === "skills") await loadSkills(host as unknown as ClawdbotApp);
   if (host.tab === "nodes") {

ui/src/ui/app-view-state.ts

@@ -112,6 +112,10 @@ export type AppViewState = {
   sessionsFilterLimit: string;
   sessionsIncludeGlobal: boolean;
   sessionsIncludeUnknown: boolean;
+  analyticsLoading: boolean;
+  analyticsError: string | null;
+  analyticsData: unknown | null;
+  analyticsDays: number;
   cronLoading: boolean;
   cronJobs: CronJob[];
   cronStatus: CronStatus | null;

ui/src/ui/app.ts

@@ -202,6 +202,11 @@ export class ClawdbotApp extends LitElement {
   @state() sessionsIncludeGlobal = true;
   @state() sessionsIncludeUnknown = false;
 
+  @state() analyticsLoading = false;
+  @state() analyticsError: string | null = null;
+  @state() analyticsData: unknown | null = null;
+  @state() analyticsDays = 30;
+
   @state() cronLoading = false;
   @state() cronJobs: CronJob[] = [];
   @state() cronStatus: CronStatus | null = null;

ui/src/ui/controllers/analytics.ts

@@ -0,0 +1,28 @@
+import type { GatewayBrowserClient } from "../gateway.js";
+import type { CostUsageSummary } from "../views/analytics.js";
+
+export type AnalyticsState = {
+  client: GatewayBrowserClient;
+  analyticsLoading: boolean;
+  analyticsError: string | null;
+  analyticsData: CostUsageSummary | null;
+  analyticsDays: number;
+};
+
+export async function loadAnalytics(state: AnalyticsState): Promise<void> {
+  state.analyticsLoading = true;
+  state.analyticsError = null;
+
+  try {
+    const res = await state.client.request("usage.cost", { days: state.analyticsDays });
+    if (res.ok && res.result) {
+      state.analyticsData = res.result as CostUsageSummary;
+    } else {
+      state.analyticsError = res.error?.message ?? "Failed to load usage data";
+    }
+  } catch (err) {
+    state.analyticsError = err instanceof Error ? err.message : "Failed to load usage data";
+  } finally {
+    state.analyticsLoading = false;
+  }
+}

ui/src/ui/navigation.ts

@@ -4,7 +4,7 @@ export const TAB_GROUPS = [
   { label: "Chat", tabs: ["chat"] },
   {
     label: "Control",
-    tabs: ["overview", "channels", "instances", "sessions", "cron"],
+    tabs: ["overview", "channels", "instances", "sessions", "cron", "analytics"],
   },
   { label: "Agent", tabs: ["skills", "nodes"] },
   { label: "Settings", tabs: ["config", "debug", "logs"] },
@@ -16,6 +16,7 @@ export type Tab =
   | "instances"
   | "sessions"
   | "cron"
+  | "analytics"
   | "skills"
   | "nodes"
   | "chat"
@@ -29,6 +30,7 @@ const TAB_PATHS: Record<Tab, string> = {
   instances: "/instances",
   sessions: "/sessions",
   cron: "/cron",
+  analytics: "/analytics",
   skills: "/skills",
   nodes: "/nodes",
   chat: "/chat",
@@ -114,6 +116,8 @@ export function iconForTab(tab: Tab): IconName {
       return "fileText";
     case "cron":
       return "loader";
+    case "analytics":
+      return "barChart";
     case "skills":
       return "zap";
     case "nodes":
@@ -141,6 +145,8 @@ export function titleForTab(tab: Tab) {
       return "Sessions";
     case "cron":
       return "Cron Jobs";
+    case "analytics":
+      return "Analytics";
     case "skills":
       return "Skills";
     case "nodes":
@@ -170,6 +176,8 @@ export function subtitleForTab(tab: Tab) {
       return "Inspect active sessions and adjust per-session defaults.";
     case "cron":
       return "Schedule wakeups and recurring agent runs.";
+    case "analytics":
+      return "Token usage and cost trends over time.";
     case "skills":
       return "Manage skill availability and API key injection.";
     case "nodes":

ui/src/ui/views/analytics.ts

@@ -0,0 +1,240 @@
+import { html, nothing } from "lit";
+
+export type CostUsageTotals = {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  totalTokens: number;
+  totalCost: number;
+  missingCostEntries: number;
+};
+
+export type CostUsageDailyEntry = CostUsageTotals & {
+  date: string;
+};
+
+export type CostUsageSummary = {
+  updatedAt: number;
+  days: number;
+  daily: CostUsageDailyEntry[];
+  totals: CostUsageTotals;
+};
+
+export type AnalyticsProps = {
+  loading: boolean;
+  error: string | null;
+  data: CostUsageSummary | null;
+  days: number;
+  onDaysChange: (days: number) => void;
+  onRefresh: () => void;
+};
+
+function formatNumber(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
+  return n.toFixed(0);
+}
+
+function formatCost(n: number): string {
+  if (n === 0) return "$0.00";
+  if (n < 0.01) return `$${n.toFixed(4)}`;
+  return `$${n.toFixed(2)}`;
+}
+
+function renderBarChart(daily: CostUsageDailyEntry[], metric: "totalTokens" | "totalCost") {
+  if (!daily.length) {
+    return html`<div class="chart-empty">No data for this period</div>`;
+  }
+
+  const values = daily.map((d) => d[metric]);
+  const max = Math.max(...values, 1);
+  const barWidth = Math.max(8, Math.min(40, Math.floor(600 / daily.length) - 4));
+
+  return html`
+    <div class="chart-container">
+      <div class="chart-bars">
+        ${daily.map((entry, i) => {
+          const value = entry[metric];
+          const height = Math.max(2, (value / max) * 150);
+          const label = metric === "totalCost" ? formatCost(value) : formatNumber(value);
+          const dateLabel = entry.date.slice(5); // MM-DD
+          return html`
+            <div class="chart-bar-wrapper" style="width: ${barWidth}px">
+              <div class="chart-bar-tooltip">${label}</div>
+              <div
+                class="chart-bar"
+                style="height: ${height}px; width: ${barWidth - 2}px"
+                title="${entry.date}: ${label}"
+              ></div>
+              <div class="chart-bar-label">${dateLabel}</div>
+            </div>
+          `;
+        })}
+      </div>
+    </div>
+  `;
+}
+
+export function renderAnalytics(props: AnalyticsProps) {
+  const { loading, error, data, days } = props;
+  const totals = data?.totals;
+
+  return html`
+    <style>
+      .analytics-controls {
+        display: flex;
+        gap: 12px;
+        align-items: center;
+        margin-bottom: 20px;
+      }
+      .analytics-controls select {
+        padding: 6px 12px;
+        border-radius: 6px;
+        border: 1px solid var(--border);
+        background: var(--bg-elevated);
+        color: var(--fg);
+        font-size: 14px;
+      }
+      .chart-container {
+        overflow-x: auto;
+        padding: 20px 0;
+      }
+      .chart-bars {
+        display: flex;
+        align-items: flex-end;
+        gap: 4px;
+        min-height: 180px;
+        padding-bottom: 24px;
+      }
+      .chart-bar-wrapper {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        position: relative;
+      }
+      .chart-bar {
+        background: var(--accent, #6366f1);
+        border-radius: 3px 3px 0 0;
+        transition: opacity 0.15s;
+      }
+      .chart-bar:hover {
+        opacity: 0.8;
+      }
+      .chart-bar-label {
+        font-size: 10px;
+        color: var(--fg-muted);
+        margin-top: 4px;
+        white-space: nowrap;
+      }
+      .chart-bar-tooltip {
+        font-size: 11px;
+        color: var(--fg-muted);
+        margin-bottom: 4px;
+        opacity: 0;
+        transition: opacity 0.15s;
+      }
+      .chart-bar-wrapper:hover .chart-bar-tooltip {
+        opacity: 1;
+      }
+      .chart-empty {
+        color: var(--fg-muted);
+        padding: 40px;
+        text-align: center;
+      }
+      .analytics-grid {
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+        gap: 16px;
+        margin-bottom: 24px;
+      }
+      .analytics-stat {
+        background: var(--bg-elevated);
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        padding: 16px;
+      }
+      .analytics-stat-label {
+        font-size: 12px;
+        color: var(--fg-muted);
+        margin-bottom: 4px;
+      }
+      .analytics-stat-value {
+        font-size: 24px;
+        font-weight: 600;
+        font-variant-numeric: tabular-nums;
+      }
+    </style>
+
+    <section class="card">
+      <div class="card-title">Usage Summary</div>
+      <div class="card-sub">Token consumption and estimated costs.</div>
+
+      <div class="analytics-controls" style="margin-top: 16px;">
+        <label>
+          Period:
+          <select
+            .value=${String(days)}
+            @change=${(e: Event) => {
+              const value = parseInt((e.target as HTMLSelectElement).value, 10);
+              props.onDaysChange(value);
+            }}
+          >
+            <option value="7">Last 7 days</option>
+            <option value="14">Last 14 days</option>
+            <option value="30">Last 30 days</option>
+            <option value="90">Last 90 days</option>
+          </select>
+        </label>
+        <button class="btn" @click=${() => props.onRefresh()} ?disabled=${loading}>
+          ${loading ? "Loading..." : "Refresh"}
+        </button>
+      </div>
+
+      ${error ? html`<div class="callout danger">${error}</div>` : nothing}
+
+      ${totals
+        ? html`
+            <div class="analytics-grid">
+              <div class="analytics-stat">
+                <div class="analytics-stat-label">Total Tokens</div>
+                <div class="analytics-stat-value">${formatNumber(totals.totalTokens)}</div>
+              </div>
+              <div class="analytics-stat">
+                <div class="analytics-stat-label">Input Tokens</div>
+                <div class="analytics-stat-value">${formatNumber(totals.input)}</div>
+              </div>
+              <div class="analytics-stat">
+                <div class="analytics-stat-label">Output Tokens</div>
+                <div class="analytics-stat-value">${formatNumber(totals.output)}</div>
+              </div>
+              <div class="analytics-stat">
+                <div class="analytics-stat-label">Cache Read</div>
+                <div class="analytics-stat-value">${formatNumber(totals.cacheRead)}</div>
+              </div>
+              <div class="analytics-stat">
+                <div class="analytics-stat-label">Cache Write</div>
+                <div class="analytics-stat-value">${formatNumber(totals.cacheWrite)}</div>
+              </div>
+              <div class="analytics-stat">
+                <div class="analytics-stat-label">Est. Cost</div>
+                <div class="analytics-stat-value">${formatCost(totals.totalCost)}</div>
+              </div>
+            </div>
+          `
+        : nothing}
+    </section>
+
+    <section class="card" style="margin-top: 18px;">
+      <div class="card-title">Daily Tokens</div>
+      <div class="card-sub">Token usage per day.</div>
+      ${data?.daily ? renderBarChart(data.daily, "totalTokens") : html`<div class="chart-empty">${loading ? "Loading..." : "No data"}</div>`}
+    </section>
+
+    <section class="card" style="margin-top: 18px;">
+      <div class="card-title">Daily Cost</div>
+      <div class="card-sub">Estimated cost per day.</div>
+      ${data?.daily ? renderBarChart(data.daily, "totalCost") : html`<div class="chart-empty">${loading ? "Loading..." : "No data"}</div>`}
+    </section>
+  `;
+}