claude-rpc 0.3.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Archer Simmons
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,300 @@
+<div align="center">
+
+<img src="https://cdn.qualit.ly/clawd-working-building.gif" width="120" alt="working" />
+<img src="https://cdn.qualit.ly/clawd-working-typing.gif" width="120" alt="thinking" />
+<img src="https://cdn.qualit.ly/clawd-notification.gif" width="120" alt="notification" />
+<img src="https://cdn.qualit.ly/clawd-sleeping.gif" width="120" alt="idle" />
+
+# claude-rpc
+
+**Discord Rich Presence for [Claude Code](https://claude.com/claude-code).**
+Your model, project, current tool, tokens, and lifetime stats — live in your Discord profile.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node 18+](https://img.shields.io/badge/node-%3E%3D18-43853d.svg?logo=node.js&logoColor=white)](https://nodejs.org)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-hooks-d97757.svg)](https://claude.com/claude-code)
+[![Discord RPC](https://img.shields.io/badge/Discord-RPC-5865F2.svg?logo=discord&logoColor=white)](https://discord.com/developers/docs/topics/rpc)
+
+</div>
+
+---
+
+<div align="center">
+  <img src="docs/demo.gif" width="560" alt="Discord Rich Presence card: Claude Code, working in claude-rpc on Opus 4.7" />
+</div>
+
+Driven entirely by Claude Code's hook system. Zero polling, zero overhead between sessions.
+
+<div align="center">
+
+<sub>Sample badges (your numbers, your README):</sub>
+
+<img src="https://img.shields.io/badge/claude%20%C2%B7%207d-12.4h-4c1" alt="hours" />&nbsp;<img src="https://img.shields.io/badge/streak-23%20days-fe7d37" alt="streak" />&nbsp;<img src="https://img.shields.io/badge/claude%20cost%20%C2%B7%2030d-$48.20-3a7" alt="cost" />&nbsp;<img src="https://img.shields.io/badge/lines%20%C2%B7%20all--time-24.1k-08c" alt="lines" />&nbsp;<img src="https://img.shields.io/badge/prompts%20%C2%B7%2030d-1.2k-5865F2" alt="prompts" />
+
+</div>
+
+> **What's new in v0.2.0** — Cost estimation, code churn, languages, MCP/built-in split, bash + web + subagent leaderboards, redesigned web dashboard with SSE push, six-tab Electron settings GUI, new `insights` and `badge` subcommands. [Full release notes →](https://github.com/rar-file/claude-rpc/releases/tag/v0.2.0)
+
+## Features
+
+**In Discord**
+
+| | |
+| :--- | :--- |
+| 🔴 **Live status** | Model, project, current tool/file, and token counts update as you work |
+| 🎞️ **Status art** | Large image swaps between *working*, *thinking*, *idle*, *stale*, *notification* |
+| 🔁 **Rotation frames** | Cycle through today's stats, streak, top file, lifetime totals, anything you template |
+| 🐙 **Auto GitHub button** | When your cwd is a git repo with a github origin, a *View on GitHub* button appears |
+
+**Beyond Discord**
+
+| | |
+| :--- | :--- |
+| 📊 **All-time aggregates** | Hours, prompts, tokens, streaks, hotspots, **lines changed, languages, cost, bash usage, web domains, subagent runs** — incremental scanner over `~/.claude/projects/*.jsonl` |
+| 💰 **Cost estimate** | Per-model spend (Opus/Sonnet/Haiku) using public list prices — editable in `src/pricing.js` |
+| 🧠 **Insights** | `claude-rpc insights` generates 3–5 contextual lines: weekly trend, peak weekday, hotspot file, cost pace, streak progress |
+| 🖥️ **CLI dashboard** | `claude-rpc status` — heatmap, hour histogram, top tools / files / projects / languages / bash commands / cost |
+| 🌐 **Web dashboard** | `claude-rpc serve` — range selector (7d / 30d / 90d / 1y / All), live SSE updates, project drilldown, day-detail modal, achievements, theme toggle |
+| 🪪 **README badges** | `claude-rpc badge --metric hours --range 7d --out h.svg` (or live at `/api/badge.svg?metric=…`) |
+| ⚙️ **Config GUI** | Electron app with six tabs: Presence (drag-reorder, variable autocomplete, presets), Discord, Assets, Timing, Daemon (start/stop/restart, tail log), Stats |
+
+## Screens
+
+<table>
+<tr>
+<td align="center" width="50%"><b>Web dashboard</b><br/><sub><code>claude-rpc serve</code></sub><br/><br/><img src="docs/dashboard.png" alt="Web dashboard with range selector, activity chart, heatmap, cost panel, languages stack, and leaderboards" /></td>
+<td align="center" width="50%"><b>Settings GUI</b><br/><sub><code>npm run dashboard</code></sub><br/><br/><img src="docs/electron.png" alt="Electron config editor with Presence / Discord / Assets / Timing / Daemon / Stats tabs" /></td>
+</tr>
+</table>
+
+## Install
+
+**Windows (no Node required)** — grab the latest portable exe:
+
+```sh
+# From https://github.com/rar-file/claude-rpc/releases/latest
+# Download claude-rpc.exe, drop it anywhere on PATH.
+claude-rpc setup
+claude-rpc start
+```
+
+**Any OS (from source)** — Node 18+:
+
+```sh
+git clone https://github.com/rar-file/claude-rpc.git
+cd claude-rpc
+npm install
+cp config.example.json config.json
+npm link            # optional, makes `claude-rpc` global
+```
+
+Requires the Discord **desktop** client (RPC IPC is unavailable in the browser client) and Claude Code with hook support.
+
+## Quick start
+
+```sh
+node ./src/cli.js setup      # register hooks into ~/.claude/settings.json
+node ./src/cli.js start      # launch the daemon (detached)
+node ./src/cli.js status     # CLI dashboard
+node ./src/cli.js serve      # web dashboard at http://127.0.0.1:47474
+```
+
+Open Claude Code in any project. Hooks fire on `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Notification`, `Stop`, and `SessionEnd`, and the daemon pushes updated presence to Discord within a second.
+
+If you `npm link` (or install the packaged exe), every command above becomes `claude-rpc <command>`.
+
+## Discord app setup
+
+1. Open the [Discord Developer Portal](https://discord.com/developers/applications) and create a new application named something like `Claude Code`.
+2. Copy the **Application ID** into `config.json` under `clientId`.
+3. *(Optional)* Under **Rich Presence → Art Assets**, upload images named `claude`, `working`, `thinking`, `idle`, `notification` to match the keys in `statusAssets`.
+4. Or skip uploading and use direct URLs in `statusAssets` (e.g. `"https://example.com/working.gif"`). Modern Discord clients fetch them through their media proxy.
+
+## Commands
+
+| Command       | Description                                              |
+| ------------- | -------------------------------------------------------- |
+| `setup`       | Install hooks into `~/.claude/settings.json`             |
+| `uninstall`   | Remove hooks                                             |
+| `start`       | Start the daemon (detached)                              |
+| `stop`        | Stop the daemon                                          |
+| `restart`     | Stop then start                                          |
+| `status`      | Current session + all-time dashboard                     |
+| `today`       | Today's stats + 24h histogram                            |
+| `week`        | This week's stats + daily breakdown                      |
+| `serve`       | Open the local web dashboard (port 47474)                |
+| `preview`     | Show how each rotation frame renders right now           |
+| `scan`        | Incrementally rescan `~/.claude/projects` for aggregates |
+| `rescan`      | Force re-parse every transcript                          |
+| `insights`    | Print 3–5 auto-generated insight lines                   |
+| `badge`       | Render a Shields-style SVG (`--metric hours\|streak\|cost\|lines`, `--range 7d\|30d\|all`, `--out file.svg`) |
+| `tail`        | Tail the daemon log                                      |
+| `daemon`      | Run the daemon in the foreground (for debugging)         |
+
+## Config GUI
+
+```sh
+cd dashboard
+npm install
+npm start                # dev mode
+npm run build            # → dist/claude-rpc-dashboard.exe (Windows portable)
+```
+
+The Electron app reads and writes `config.json` directly. The daemon hot-reloads.
+
+## How it works
+
+Three cooperating pieces, glued by JSON files on disk.
+
+```
+   Claude Code                                          Discord desktop
+        │                                                     ▲
+        │ lifecycle event (stdin JSON)                        │ IPC frame
+        ▼                                                     │
+   ┌──────────┐    state.json    ┌──────────┐                 │
+   │ hook.js  │ ───────────────▶ │ daemon.js│ ────────────────┘
+   └──────────┘                  └──────────┘
+                                       ▲
+                                       │ aggregate.json
+                                       │
+                                ┌────────────┐
+                                │ scanner.js │ ◀── ~/.claude/projects/*.jsonl
+                                └────────────┘
+```
+
+1. **Hook** (`src/hook.js`) — Claude Code spawns it on every lifecycle event. Parses the event JSON from stdin and mutates the shared state file.
+2. **Daemon** (`src/daemon.js`) — Long-running. Connects to Discord's local IPC, watches the state file plus periodic transcript scans, pushes presence frames every few seconds.
+3. **Scanner** (`src/scanner.js`) — Walks `~/.claude/projects/**/*.jsonl` transcripts for all-time aggregates (active time, prompts, tool calls, tokens, streaks, hour-of-day, top files / projects). Cached at `~/.claude-rpc/aggregate.json` for incremental updates.
+
+Persistent state lives in a few well-known places:
+
+| Path | What |
+| ---- | ---- |
+| `$TMPDIR/claude-rpc/state.json` | Current session, volatile |
+| `~/.claude-rpc/aggregate.json` | All-time aggregates |
+| `~/.claude-rpc/scan-cache.json` | Per-transcript scan cache |
+| `~/.claude/settings.json` | Hook registrations (managed by `setup`) |
+
+<details>
+<summary><b>Configuration reference</b></summary>
+
+`config.json` keys, all optional unless noted:
+
+| Key                       | Default | Notes                                                               |
+| ------------------------- | ------- | ------------------------------------------------------------------- |
+| `clientId`                | —       | **Required.** Discord application ID                                |
+| `updateIntervalMs`        | `4000`  | How often the daemon pushes to Discord                              |
+| `rotationIntervalMs`      | `12000` | How fast rotation frames cycle                                      |
+| `rescanIntervalSec`       | `300`   | How often transcripts are re-aggregated                             |
+| `idleThresholdSec`        | `60`    | No activity for this long → status `idle`                           |
+| `staleSessionMin`         | `5`     | No activity for this long (minutes) → status `stale`; presence is cleared |
+| `notificationWindowSec`   | `8`     | How long the `notification` status sticks                           |
+| `showElapsed`             | `true`  | Include the elapsed timer                                           |
+| `activityType`            | `0`     | `0` Playing, `2` Listening, `3` Watching, `5` Competing             |
+| `statusAssets`            | `{}`    | Image per status (working / thinking / idle / stale / notification) |
+| `presence.largeImageKey`  | —       | Fallback large image when no `statusAssets` match                   |
+| `presence.largeImageText` | —       | Tooltip on hover                                                    |
+| `presence.smallImageKey`  | —       | Small badge in the corner of the large image                        |
+| `presence.smallImageText` | —       | Tooltip on hover                                                    |
+| `presence.rotation`       | `[]`    | Array of frames, each `{ details, state, requires? }`               |
+| `presence.buttons`        | `[]`    | Up to 2 `{ label, url }` buttons                                    |
+| `statusIcons`             | `{}`    | Small image key per status (empty string hides it)                  |
+
+### Rotation frames
+
+```jsonc
+{
+  "presence": {
+    "rotation": [
+      { "details": "{statusVerbose} in {project}",   "state": "{modelPretty}" },
+      { "details": "{currentToolPretty} · {currentFilePretty}",
+        "state":   "{tokensFmt} tokens",
+        "requires": ["currentFile"] },
+      { "details": "Today · {todayHours}",
+        "state":   "{todayPromptsLabel}",
+        "requires": ["todayActiveMs"] }
+    ]
+  }
+}
+```
+
+Each frame has:
+
+- `details` — bold first line (Discord max 128 chars)
+- `state` — lighter second line (Discord max 128 chars)
+- `requires` *(optional)* — a variable name or array of names. The frame is skipped if any required variable is empty / `0`. Lets you have context-dependent frames (e.g. only show the *current tool* frame when there's actually a tool running).
+
+</details>
+
+<details>
+<summary><b>Template variables</b></summary>
+
+Both `details` and `state` (and button labels and URLs) support `{name}` substitution.
+
+| Variable                | Sample             |
+| ----------------------- | ------------------ |
+| `{statusVerbose}`       | `Working`          |
+| `{project}`             | `claude-rpc`       |
+| `{modelPretty}`         | `Opus 4.7`         |
+| `{currentToolPretty}`   | `Edit`             |
+| `{currentFilePretty}`   | `src/app/page.tsx` |
+| `{tokensFmt}`           | `2.3k`             |
+| `{messagesLabel}`       | `8 prompts`        |
+| `{projectSessionLabel}` | `Session #1`       |
+| `{projectHours}`        | `22m`              |
+| `{todayHours}`          | `56m`              |
+| `{weekHours}`           | `3.1h`             |
+| `{streakLabel}`         | `7-day streak`     |
+| `{daysSinceFirstLabel}` | `Day 31`           |
+| `{allHours}`            | `52h`              |
+| `{allTokensFmt}`        | `2.82B`            |
+| `{peakHour}`            | `22:00`            |
+| `{topEditedFile}`       | `index.html`       |
+| `{linesAddedFmt}`       | `24k`              |
+| `{todayLinesAddedFmt}`  | `320`              |
+| `{linesNetFmt}`         | `+18k`             |
+| `{topLanguage}`         | `TypeScript`       |
+| `{languagesLabel}`      | `TypeScript · Python · Rust` |
+| `{topBashCmdLabel}`     | `git × 820`        |
+| `{topDomainLabel}`      | `docs.anthropic.com × 28` |
+| `{subagentLabel}`       | `Explore × 18`     |
+| `{mcpToolPercentLabel}` | `12% MCP`          |
+| `{todayCostFmt}`        | `$1.23`            |
+| `{allCostFmt}`          | `$89.42`           |
+| `{weekdayLabel}`        | `Thursday`         |
+| `{startTimeLabel}`      | `started 09:14`    |
+
+Run `node ./src/cli.js preview` to see every frame rendered with your real data, including which ones would be hidden by their `requires`.
+
+</details>
+
+## Badges
+
+Generate a Shields-style SVG you can drop into a README:
+
+```sh
+claude-rpc badge --metric hours  --range 7d --out claude-hours.svg
+claude-rpc badge --metric streak              --out claude-streak.svg
+claude-rpc badge --metric cost   --range 30d  --out claude-cost.svg
+claude-rpc badge --metric lines  --range all  --out claude-lines.svg
+```
+
+While the daemon's `serve` command is running, the same data is also available live at:
+
+```
+http://127.0.0.1:47474/api/badge.svg?metric=hours&range=7d
+```
+
+Cost numbers come from `src/pricing.js`, seeded with **approximate** public list prices for Anthropic models. Edit that file to override — your actual Claude Code subscription bill is unrelated.
+
+## Troubleshooting
+
+**Discord doesn't pick up presence.** The Discord *desktop* app must be running. The browser client doesn't expose the local IPC bridge. Verify `clientId` matches your Discord application, and run `claude-rpc tail` to watch the daemon log live.
+
+**Hooks don't fire.** Run `claude-rpc setup` and check the `hooks` section of `~/.claude/settings.json`. Restart Claude Code afterwards so it re-reads the hook config.
+
+**Elapsed timer resets on rotation.** Update to the current version. Older builds passed timestamps in seconds; Discord expects milliseconds.
+
+## License
+
+[MIT](LICENSE) © Archer Simmons

package/bin/claude-rpc.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli.js';

package/config.example.json

@@ -0,0 +1,67 @@
+{
+  "clientId": "1506443909406920948",
+  "appName": "Claude Code",
+  "updateIntervalMs": 4000,
+  "rotationIntervalMs": 12000,
+  "rescanIntervalSec": 300,
+  "idleThresholdSec": 60,
+  "staleSessionMin": 5,
+  "hideWhenStale": true,
+  "notificationWindowSec": 8,
+  "showElapsed": true,
+  "activityType": 0,
+  "statusAssets": {
+    "working":      "https://cdn.qualit.ly/clawd-working-building.gif",
+    "thinking":     "https://cdn.qualit.ly/clawd-working-typing.gif",
+    "idle":         "https://cdn.qualit.ly/clawd-sleeping.gif",
+    "stale":        "https://cdn.qualit.ly/clawd-sleeping.gif",
+    "notification": "https://cdn.qualit.ly/clawd-notification.gif"
+  },
+  "presence": {
+    "largeImageKey": "https://cdn.qualit.ly/clawd-sleeping.gif",
+    "largeImageText": "{modelPretty} · {allHours} on Claude · {streakLabel}",
+    "smallImageKey": "{statusIcon}",
+    "smallImageText": "{statusVerbose}",
+    "byStatus": {
+      "working": {
+        "details": "Working in {project}",
+        "state":   "{currentToolPretty} · {currentFilePretty} · {tokensFmt} tokens",
+        "largeImageText": "Working on a {fileLang} file"
+      },
+      "thinking": {
+        "details": "Thinking in {project}",
+        "state":   "{modelPretty} · {messagesLabel} · {tokensFmt} tokens",
+        "largeImageText": "Reasoning with {modelPretty}"
+      },
+      "notification": {
+        "details": "Waiting on you · {project}",
+        "state":   "{modelPretty} · {messagesLabel}",
+        "largeImageText": "Permission needed"
+      },
+      "idle": {
+        "details": "Idle in {project}",
+        "state":   "{modelPretty} · {todayHours} today",
+        "largeImageText": "Idle · {modelPretty}",
+        "rotation": [
+          { "details": "This week · {weekHours}",           "state": "{weekPromptsLabel} · {weekTokensFmt} tokens",    "requires": ["weekActiveMs"] },
+          { "details": "{streakLabel}",                     "state": "{daysSinceFirstLabel} · {allSessionsLabel}",     "requires": ["streakIsMilestone"] },
+          { "details": "Hotspot · {topEditedFile}",         "state": "{topEditedCountLabel} all-time",                 "requires": ["topEditedCount"] },
+          { "details": "{allHours} on Claude all-time",     "state": "{allSessionsLabel} · {allMessagesFmt} prompts",  "requires": ["allSessions"] },
+          { "details": "Lifetime · {allTokensFmt} tokens",  "state": "{allToolsFmt} tool calls · {allFilesFmt} files", "requires": ["allTools"] },
+          { "details": "Code churn · {linesAddedFmt} added","state": "{linesNetFmt} net · {topLanguage}",              "requires": ["topLanguage"] },
+          { "details": "Cost · {todayCostFmt} today",       "state": "{allCostFmt} all-time",                          "requires": ["allCost"] }
+        ]
+      }
+    },
+    "buttons": [
+      { "label": "Claude Code", "url": "https://claude.com/claude-code" }
+    ]
+  },
+  "statusIcons": {
+    "working":      "working",
+    "thinking":     "thinking",
+    "idle":         "idle",
+    "notification": "",
+    "stale":        ""
+  }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "claude-rpc",
+  "version": "0.3.8",
+  "description": "Discord Rich Presence for Claude Code — live model, project, tokens, and lifetime stats driven by Claude Code's hook system.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Archer Simmons",
+  "bin": {
+    "claude-rpc": "./bin/claude-rpc.js"
+  },
+  "scripts": {
+    "start": "node ./src/daemon.js",
+    "setup": "node ./src/cli.js setup",
+    "status": "node ./src/cli.js status",
+    "stop": "node ./src/cli.js stop",
+    "hook": "node ./src/hook.js",
+    "serve": "node ./src/cli.js serve",
+    "scan": "node ./src/cli.js scan",
+    "insights": "node ./src/cli.js insights",
+    "badge": "node ./src/cli.js badge",
+    "dashboard": "npm --prefix dashboard start",
+    "build:exe": "node ./scripts/build-exe.js",
+    "prep:dashboard": "node ./scripts/prep-dashboard.js",
+    "dist:mac": "npm run build:exe && npm run prep:dashboard && npm --prefix dashboard run dist:mac",
+    "dist:win": "npm run build:exe && npm run prep:dashboard && npm --prefix dashboard run dist:win"
+  },
+  "dependencies": {
+    "@xhayper/discord-rpc": "^1.2.1"
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.0",
+    "postject": "^1.0.0-alpha.6"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "discord",
+    "discord-rpc",
+    "rich-presence",
+    "anthropic",
+    "cli"
+  ],
+  "files": [
+    "bin",
+    "src",
+    "config.example.json",
+    "LICENSE",
+    "README.md"
+  ]
+}

package/src/badge.js

@@ -0,0 +1,144 @@
+// Shields-style SVG badge generator. Pure function: aggregate + flags → SVG string.
+// Consumed by `claude-rpc badge` and `GET /api/badge.svg`.
+
+import { dayKey } from './scanner.js';
+import { fmtCost } from './pricing.js';
+
+const COLORS = {
+  hours:  { left: '#555', right: '#4c1' },     // green
+  streak: { left: '#555', right: '#fe7d37' },  // orange
+  cost:   { left: '#555', right: '#3a7' },     // teal-green
+  lines:  { left: '#555', right: '#08c' },     // blue
+  prompts:{ left: '#555', right: '#5865F2' },  // discord blurple
+  tokens: { left: '#555', right: '#a55' },     // dim red
+  files:  { left: '#555', right: '#aa6' },     // olive
+};
+
+function pickWindow(byDay, range) {
+  if (!byDay) return [];
+  if (range === 'all') return Object.entries(byDay);
+  const days = parseInt(range, 10);
+  if (!Number.isFinite(days) || days <= 0) return Object.entries(byDay);
+  const today = new Date(); today.setHours(0, 0, 0, 0);
+  const out = [];
+  for (let i = 0; i < days; i++) {
+    const d = new Date(today); d.setDate(d.getDate() - i);
+    const k = dayKey(d.getTime());
+    if (byDay[k]) out.push([k, byDay[k]]);
+  }
+  return out;
+}
+
+function fmtHoursLabel(ms) {
+  if (!ms) return '0h';
+  const h = ms / 3_600_000;
+  if (h < 1) return `${Math.round(h * 60)}m`;
+  if (h < 10) return `${h.toFixed(1)}h`;
+  return `${Math.round(h)}h`;
+}
+
+function fmtNum(n) {
+  if (!n) return '0';
+  if (n < 1000) return String(n);
+  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
+  if (n < 1_000_000_000) return `${(n / 1_000_000).toFixed(2)}M`;
+  return `${(n / 1_000_000_000).toFixed(2)}B`;
+}
+
+// Compute label/value pair for the requested metric.
+function valueFor(aggregate, metric, range) {
+  const a = aggregate || {};
+  const window = pickWindow(a.byDay, range);
+
+  const rangeLabel = range === 'all' ? 'all-time' : range;
+
+  switch (metric) {
+    case 'hours': {
+      const ms = window.reduce((s, [, d]) => s + (d.activeMs || 0), 0);
+      return { label: `claude · ${rangeLabel}`, value: fmtHoursLabel(ms) };
+    }
+    case 'streak': {
+      return { label: 'streak', value: `${a.streak || 0} days` };
+    }
+    case 'cost': {
+      const cost = window.reduce((s, [, d]) => s + (d.cost || 0), 0);
+      return { label: `claude cost · ${rangeLabel}`, value: fmtCost(cost) };
+    }
+    case 'lines': {
+      const lines = window.reduce((s, [, d]) => s + (d.linesAdded || 0), 0);
+      return { label: `lines · ${rangeLabel}`, value: fmtNum(lines) };
+    }
+    case 'prompts': {
+      const p = window.reduce((s, [, d]) => s + (d.userMessages || 0), 0);
+      return { label: `prompts · ${rangeLabel}`, value: fmtNum(p) };
+    }
+    case 'tokens': {
+      const t = window.reduce((s, [, d]) =>
+        s + (d.inputTokens || 0) + (d.outputTokens || 0)
+        + (d.cacheReadTokens || 0) + (d.cacheWriteTokens || 0), 0);
+      return { label: `tokens · ${rangeLabel}`, value: fmtNum(t) };
+    }
+    case 'files': {
+      return { label: 'files touched', value: fmtNum(a.uniqueFiles || 0) };
+    }
+    default:
+      return { label: metric, value: '—' };
+  }
+}
+
+function escapeXml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+// Approximate text width in pixels for Verdana 11px. Good enough for badges.
+// Widens slightly to compensate for variable-width glyphs.
+function textWidth(s) {
+  let w = 0;
+  for (const ch of String(s)) {
+    if (/[il1.\s]/.test(ch)) w += 4;
+    else if (/[A-Z]/.test(ch)) w += 8;
+    else w += 6.5;
+  }
+  return Math.ceil(w);
+}
+
+export function renderBadge({ label, value, color }) {
+  const PAD = 8;
+  const labelW = textWidth(label) + PAD * 2;
+  const valueW = textWidth(value) + PAD * 2;
+  const total = labelW + valueW;
+  const leftColor = color?.left || '#555';
+  const rightColor = color?.right || '#4c1';
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${total}" height="20" role="img" aria-label="${escapeXml(label)}: ${escapeXml(value)}">
+  <title>${escapeXml(label)}: ${escapeXml(value)}</title>
+  <linearGradient id="s" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <clipPath id="r"><rect width="${total}" height="20" rx="3" fill="#fff"/></clipPath>
+  <g clip-path="url(#r)">
+    <rect width="${labelW}" height="20" fill="${leftColor}"/>
+    <rect x="${labelW}" width="${valueW}" height="20" fill="${rightColor}"/>
+    <rect width="${total}" height="20" fill="url(#s)"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110">
+    <text aria-hidden="true" x="${(labelW * 10) / 2}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="${(labelW - PAD * 2) * 10}">${escapeXml(label)}</text>
+    <text x="${(labelW * 10) / 2}" y="140" transform="scale(.1)" fill="#fff" textLength="${(labelW - PAD * 2) * 10}">${escapeXml(label)}</text>
+    <text aria-hidden="true" x="${(labelW + valueW / 2) * 10}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="${(valueW - PAD * 2) * 10}">${escapeXml(value)}</text>
+    <text x="${(labelW + valueW / 2) * 10}" y="140" transform="scale(.1)" fill="#fff" textLength="${(valueW - PAD * 2) * 10}">${escapeXml(value)}</text>
+  </g>
+</svg>`;
+}
+
+// Top-level convenience: aggregate + flags → SVG string.
+export function badgeSvg({ aggregate, metric = 'hours', range = '7d', label, color }) {
+  const v = valueFor(aggregate, metric, range);
+  const finalLabel = label ?? v.label;
+  const finalColor = color ?? COLORS[metric] ?? COLORS.hours;
+  return renderBadge({ label: finalLabel, value: v.value, color: finalColor });
+}