claude-rpc 0.9.1 → 0.11.0

package/README.md

@@ -255,6 +255,11 @@ The full default config is in [`src/default-config.js`](src/default-config.js)
 | `badge`          | Shields-style SVG (`--metric` `--range` `--out` `--gist`) |
 | `card`           | Poster-style SVG (`--range year\|month\|week\|all`) |
 | `github-stat`    | Embeddable profile stat card (`--handle` `--out` `--gist`) |
+| `calendar`       | Year activity heatmap SVG (`--out` `--gist`) |
+| `session-card`   | Recap card for the current session (`--out`) |
+| `statusline`     | One-line status for tmux/shell prompts (`--template`) |
+| `mcp`            | Run as an MCP server — expose your stats to Claude Code |
+| `wrapped`        | Open your animated year-in-review (Claude Wrapped) |
 | `private` / `public` / `privacy` | Per-cwd visibility toggles + status |
 | `community`      | Opt-in community totals — `on` \| `off` \| `status` \| `report` |
 | `doctor`         | Diagnostic checklist with one-line fix hints |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-rpc",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "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",

package/src/calendar.js

@@ -0,0 +1,95 @@
+// Activity calendar — a GitHub-contributions-style year heatmap of Claude
+// Code activity, rendered as an embeddable SVG (paper/terracotta brand).
+// `claude-rpc calendar --out cal.svg [--gist]`.
+
+import { dayKey } from './scanner.js';
+import { VERSION } from './version.js';
+
+const PALETTE = {
+  paper:  '#f4ede0',
+  ink:    '#1a1611',
+  inkMute:'#5c5147',
+  inkFaint:'#8a7c6d',
+  empty:  '#e1d6c0',
+  l1:     '#f6dccb',
+  l2:     '#f08a4a',
+  l3:     '#c2491e',
+  l4:     '#8f3415',
+};
+
+const MONTHS = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'];
+
+function escapeXml(s) {
+  return String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+// activeMs → one of 5 intensity buckets (0..4). 4h saturates.
+function level(ms) {
+  if (!ms) return 0;
+  const h = ms / 3_600_000;
+  if (h < 0.5) return 1;
+  if (h < 1.5) return 2;
+  if (h < 3) return 3;
+  return 4;
+}
+const FILL = [PALETTE.empty, PALETTE.l1, PALETTE.l2, PALETTE.l3, PALETTE.l4];
+
+export function renderCalendar(aggregate, { weeks = 53, generatedAt = new Date() } = {}) {
+  const byDay = aggregate?.byDay || {};
+  const cell = 12, gap = 3, step = cell + gap;
+  const padX = 36, padTop = 68, padBottom = 30;
+
+  // Build the grid ending today. Align the last column to today's weekday so
+  // rows read Sun..Sat like GitHub. We render `weeks` columns back from today.
+  const today = new Date(generatedAt);
+  today.setHours(0, 0, 0, 0);
+  const todayDow = today.getDay(); // 0=Sun
+  const totalDays = (weeks - 1) * 7 + todayDow + 1;
+
+  let cells = '';
+  let monthLabels = '';
+  let lastMonth = -1;
+  let totalActiveMs = 0, activeDays = 0;
+
+  for (let i = 0; i < totalDays; i++) {
+    const d = new Date(today);
+    d.setDate(d.getDate() - (totalDays - 1 - i));
+    const col = Math.floor(i / 7);
+    const row = d.getDay();
+    const key = dayKey(d);
+    const ms = byDay[key]?.activeMs || 0;
+    if (ms > 0) { totalActiveMs += ms; activeDays += 1; }
+    const x = padX + col * step;
+    const y = padTop + row * step;
+    cells += `<rect x="${x}" y="${y}" width="${cell}" height="${cell}" rx="2" fill="${FILL[level(ms)]}" stroke="${PALETTE.ink}" stroke-width="0.4"/>`;
+    // Month label when a new month starts in the top row region.
+    if (d.getMonth() !== lastMonth && d.getDate() <= 7) {
+      lastMonth = d.getMonth();
+      monthLabels += `<text x="${x}" y="${padTop - 9}" font-family="JetBrains Mono, ui-monospace, monospace" font-size="10" fill="${PALETTE.inkMute}">${MONTHS[d.getMonth()]}</text>`;
+    }
+  }
+
+  const W = padX + weeks * step + 14;
+  const H = padTop + 7 * step + padBottom;
+  const totalHours = (totalActiveMs / 3_600_000).toFixed(0);
+  let legend = '';
+  for (let l = 0; l < 5; l++) {
+    legend += `<rect x="${W - 150 + l * 16}" y="${H - 20}" width="${cell}" height="${cell}" rx="2" fill="${FILL[l]}" stroke="${PALETTE.ink}" stroke-width="0.4"/>`;
+  }
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}" role="img" aria-label="Claude Code activity calendar">
+  <rect width="${W}" height="${H}" fill="${PALETTE.paper}"/>
+  <text x="${padX}" y="28" font-family="Space Grotesk, Inter, system-ui, sans-serif" font-size="20" font-weight="800" fill="${PALETTE.ink}">a year on Claude Code</text>
+  <text x="${padX}" y="44" font-family="JetBrains Mono, ui-monospace, monospace" font-size="11" fill="${PALETTE.inkMute}">${escapeXml(activeDays)} active days · ${escapeXml(totalHours)}h · as of ${generatedAt.toISOString().slice(0, 10)}</text>
+  ${monthLabels}
+  ${cells}
+  <text x="${W - 170}" y="${H - 10}" font-family="JetBrains Mono, ui-monospace, monospace" font-size="9" fill="${PALETTE.inkFaint}">less</text>
+  ${legend}
+  <text x="${W - 28}" y="${H - 10}" font-family="JetBrains Mono, ui-monospace, monospace" font-size="9" fill="${PALETTE.inkFaint}">more</text>
+  <text x="${padX}" y="${H - 8}" font-family="JetBrains Mono, ui-monospace, monospace" font-size="9" fill="${PALETTE.inkFaint}">claude-rpc v${VERSION}</text>
+</svg>`;
+}
+
+export function calendarSvg({ aggregate } = {}) {
+  return renderCalendar(aggregate, {});
+}

package/src/cli.js

@@ -785,6 +785,68 @@ async function doGithubStat(argv) {
   }
 }
 
+// Build the live template-variable table the way the daemon does — current
+// state + idle/stale resolution + aggregate. Shared by statusline/session-card.
+function liveVars() {
+  const state = readState();
+  state.liveSessions = findLiveSessions({ thresholdMs: 90_000 });
+  const config = loadConfig();
+  const resolved = applyIdle(state, config);
+  return { vars: buildVars(resolved, config, readAggregate()), config };
+}
+
+// statusline — a compact one-line status for tmux / starship / shell prompts
+// and Claude Code's own statusline. `--template "..."` overrides the format.
+function doStatusline(argv) {
+  let tpl = '{statusVerbose} · {project} · {modelPretty}{tokensLabelPad}';
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--template' || argv[i] === '-t') tpl = argv[++i] || tpl;
+  }
+  const { vars } = liveVars();
+  vars.tokensLabelPad = vars.tokensLabel ? ` · ${vars.tokensLabel}` : '';
+  process.stdout.write(fillTemplate(tpl, vars));
+}
+
+// Activity calendar — GitHub-contributions-style year heatmap SVG.
+async function doCalendar(argv) {
+  const opts = { out: '', gist: false };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--out' || argv[i] === '-o') opts.out = argv[++i];
+    else if (argv[i] === '--gist') opts.gist = true;
+  }
+  const aggregate = readAggregate();
+  if (!aggregate) fail('no aggregate yet — run `claude-rpc scan` first', { code: EX_BAD_STATE });
+  const { renderCalendar } = await import('./calendar.js');
+  const svg = renderCalendar(aggregate, {});
+  if (opts.gist) return publishBadgeToGist(svg, { metric: 'calendar', range: 'year' });
+  if (opts.out) {
+    writeFileSync(opts.out, svg);
+    console.log(`${c.green}✓${c.reset} Wrote ${c.cyan}${opts.out}${c.reset} (${svg.length} bytes)`);
+  } else process.stdout.write(svg);
+}
+
+// Per-session recap card — current/most-recent session as a shareable SVG.
+async function doSessionCard(argv) {
+  const opts = { out: '' };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--out' || argv[i] === '-o') opts.out = argv[++i];
+  }
+  const { vars } = liveVars();
+  const { renderSessionCard } = await import('./session-card.js');
+  const svg = renderSessionCard(vars, {});
+  if (opts.out) {
+    writeFileSync(opts.out, svg);
+    console.log(`${c.green}✓${c.reset} Wrote ${c.cyan}${opts.out}${c.reset} (${svg.length} bytes)`);
+  } else process.stdout.write(svg);
+}
+
+// MCP server — expose stats to Claude Code over stdio. Long-running; never
+// writes to stdout except JSON-RPC frames.
+async function doMcp() {
+  const { runMcpServer } = await import('./mcp.js');
+  runMcpServer();
+}
+
 // ── Privacy commands ─────────────────────────────────────────────────────
 //
 // `claude-rpc private`        → add current cwd to ~/.claude-rpc/private-list.json
@@ -1075,11 +1137,16 @@ function help() {
     ['badge',     'Render a Shields-style SVG (--metric --range --out --gist)'],
     ['card',      'Render a poster-style SVG summary (--range year|month|week|all)'],
     ['github-stat', 'Render an embeddable profile stat card (--handle --out --gist)'],
+    ['statusline', 'One-line status for tmux/shell prompts (--template)'],
+    ['calendar',  'Year activity heatmap SVG (--out --gist)'],
+    ['session-card', 'Recap card for the current session (--out)'],
+    ['mcp',       'Run as an MCP server — expose your stats to Claude Code'],
+    ['wrapped',   'Open your animated year-in-review (Claude Wrapped)'],
     ['private',   'Mark the current directory as private (hide from Discord)'],
     ['public',    'Un-mark the current directory'],
     ['privacy',   'Show resolved visibility for the current directory'],
     ['community', 'Opt in/out of anonymous community totals (on|off|status|report)'],
-    ['doctor',    'Run a diagnostic checklist — common-failure triage'],
+    ['doctor',    'Run a diagnostic checklist — common-failure triage (--fix to auto-repair)'],
     ['tail',      'Tail the daemon log file'],
     ['daemon',    'Run daemon in foreground (debug)'],
   ];
@@ -1148,14 +1215,33 @@ const packagedDefault = IS_PACKAGED && !cmd;
     case 'badge':     await doBadge(process.argv.slice(3)); break;
     case 'card':      await doCard(process.argv.slice(3)); break;
     case 'github-stat': await doGithubStat(process.argv.slice(3)); break;
+    case 'statusline': doStatusline(process.argv.slice(3)); break;
+    case 'calendar':  await doCalendar(process.argv.slice(3)); break;
+    case 'session-card': await doSessionCard(process.argv.slice(3)); break;
+    case 'mcp':       await doMcp(); break;
+    case 'wrapped':   process.env.CLAUDE_RPC_OPEN_PATH = '/wrapped'; await import('./server/index.js'); break;
     case 'private':   doPrivate(); break;
     case 'public':    doPublic(); break;
     case 'privacy':   doPrivacy(); break;
     case 'community': await doCommunity(process.argv.slice(3)); break;
     case 'doctor': {
       const { runDoctor } = await import('./doctor.js');
-      process.exit(runDoctor());
-      break;
+      const fix = process.argv.includes('--fix');
+      const code = runDoctor();
+      if (!fix) process.exit(code);
+      // --fix: re-run setup (re-seeds/migrates config, re-wires hooks — all
+      // idempotent) and restart the daemon to pick it up. Covers the common
+      // breakages doctor flags: missing/stale hooks, bricked config, dead daemon.
+      console.log(`\n  ${c.cyan}◆ --fix${c.reset} ${c.dim}— re-running setup and restarting the daemon${c.reset}`);
+      try {
+        await runInstall({ exePath: EXE_PATH || process.execPath });
+        console.log(`  ${c.green}✓${c.reset} config + hooks repaired`);
+      } catch (e) {
+        console.log(`  ${c.red}✗${c.reset} setup step failed: ${e.message}`);
+      }
+      restartDaemon();
+      console.log(`  ${c.green}✓${c.reset} daemon restarting — run ${c.cyan}claude-rpc doctor${c.reset} again in a few seconds to confirm.`);
+      break; // let the restart timer fire before the process drains
     }
     case 'tail':
     case 'logs':

package/src/daemon.js

@@ -2,12 +2,14 @@
 import { writeFileSync, existsSync, unlinkSync, watch, appendFileSync, mkdirSync, statSync, renameSync } from 'node:fs';
 import { Client } from '@xhayper/discord-rpc';
 import { readState } from './state.js';
-import { buildVars, fillTemplate, framePasses, applyIdle, applyShipped } from './format.js';
+import { buildVars, fillTemplate, framePasses, applyIdle, applyShipped, applyTrigger } from './format.js';
 import { scan, readAggregate, findLiveSessions, readSessionTokens } from './scanner.js';
 import { detectGithubUrl } from './git.js';
 import { applyPrivacy } from './privacy.js';
 import { loadConfig } from './config.js';
 import { migrateConfig } from './install.js';
+import { desktopNotify, postWebhook, shouldWebhook, shouldNotify } from './notify.js';
+import { humanProject } from './format.js';
 import { CONFIG_PATH, STATE_PATH, PID_PATH, LOG_PATH, STATE_DIR, AGGREGATE_PATH } from './paths.js';
 
 if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true });
@@ -72,6 +74,9 @@ let liveSessions = [];
 let client = null;
 let connected = false;
 let lastPayloadHash = '';
+// Last status we acted on for outbound side-effects (webhook / desktop notify).
+// Tracked separately from the render hash so we fire once per transition.
+let lastNotifiedStatus = null;
 let reconnectTimer = null;
 // Exponential backoff for Discord reconnect: 5s → 10s → 20s → … → 300s cap.
 // Reset to RECONNECT_BASE_MS on a successful connect so the next outage
@@ -139,6 +144,8 @@ function buildActivity(opts = {}) {
   // Shipped overlay sits on top of idle/working/thinking — but never over
   // stale (we don't celebrate when Claude isn't running).
   state = applyShipped(state, config);
+  // Custom-command trigger overlay (config.triggers) — never over stale/shipped.
+  state = applyTrigger(state, config);
 
   // Pull live session tokens from the transcript file. Claude Code's hook
   // payloads don't include usage data, so state.tokens from PostToolUse
@@ -168,7 +175,13 @@ function buildActivity(opts = {}) {
   // Pick the active set of frames + any status-level largeImageText override.
   // Reset the rotation cursor when status changes so a 7-frame idle rotation
   // doesn't bleed its index into a 1-frame working state.
-  const { frames: rawFrames, largeImageTextTpl: statusLIT } = pickFrames(p, state.status);
+  let rawFrames, statusLIT;
+  if (state.status === 'trigger' && state._triggerFrame) {
+    rawFrames = [state._triggerFrame];
+    statusLIT = state._triggerFrame.largeImageText || null;
+  } else {
+    ({ frames: rawFrames, largeImageTextTpl: statusLIT } = pickFrames(p, state.status));
+  }
   if (state.status !== rotationStatus) {
     rotationIndex = 0;
     lastRotationAt = 0;
@@ -259,6 +272,33 @@ function buildActivity(opts = {}) {
   return activity;
 }
 
+// Fire desktop-notification + webhook on a status transition (once per change).
+function fireStatusSideEffects(resolved) {
+  const status = resolved.status;
+  if (status === lastNotifiedStatus) return;
+  const prev = lastNotifiedStatus;
+  lastNotifiedStatus = status;
+  try {
+    const project = humanProject(resolved.cwd) || 'Claude Code';
+    if (shouldNotify(config.notify, prev, status)) {
+      desktopNotify('Claude Code needs you', `Waiting on you in ${project}`);
+      log(`desktop notification raised (status=${status})`);
+    }
+    if (shouldWebhook(config.webhook, prev, status)) {
+      postWebhook(config.webhook.url, {
+        status,
+        project,
+        model: resolved.model || null,
+        justShipped: resolved.justShippedKind || null,
+        ts: Date.now(),
+      });
+      log(`webhook: POSTed status=${status} (${project})`);
+    }
+  } catch (e) {
+    log('status side-effect failed:', e.message);
+  }
+}
+
 async function pushPresence() {
   if (!connected || !client?.user) return;
   try {
@@ -274,6 +314,10 @@ async function pushPresence() {
     // lastPayloadHash so we don't spam the IPC.
     resolved = applyPrivacy(resolved, config);
 
+    // Outbound side-effects on a status TRANSITION (fire once per change):
+    // a desktop notification when Claude needs you, and an opt-in webhook POST.
+    fireStatusSideEffects(resolved);
+
     const hideWhenStale = config.hideWhenStale !== false;
     const privacyHidden = resolved._privacy?.visibility === 'hidden';
     if ((resolved.status === 'stale' && hideWhenStale) || privacyHidden) {

package/src/default-config.js

@@ -37,6 +37,40 @@ export const DEFAULT_CONFIG = {
   // celebratory "Just shipped" frame before falling back to the
   // underlying status. Set 0 to disable the overlay entirely.
   shippedFrameSec: 60,
+  // Daily / weekly goals (v0.10). When set (> 0), the daemon surfaces a
+  // progress frame ("2.1h / 4h · 52%") and the dashboard shows a ring.
+  // Set any field to 0/null to disable that goal.
+  goals: {
+    dailyHours: 0,     // target active hours per day
+    dailyPrompts: 0,   // target prompts per day
+    weeklyHours: 0,    // target active hours per week
+  },
+  // Monthly cost budget (v0.10). When budget.monthly > 0, the dashboard and
+  // a presence frame warn as month-to-date spend approaches it.
+  budget: {
+    monthly: 0,        // USD; 0 disables
+    warnAtPct: 80,     // surface a warning once MTD spend hits this %
+  },
+  // Outbound status webhook (v0.10). When url is set, the daemon POSTs a small
+  // JSON body on status transitions you opt into (best-effort, fire-and-forget).
+  // Pair with a Slack/Discord incoming-webhook or your own endpoint.
+  webhook: {
+    url: "",                                  // "" disables
+    on: ["shipped", "notification"],          // statuses that fire a POST
+  },
+  // Desktop notifications (v0.10). When enabled, the daemon raises a native OS
+  // notification (notify-send / osascript / PowerShell toast) when Claude needs
+  // you — so a permission prompt isn't missed while you're tabbed away.
+  notify: {
+    enabled: false,
+    onNotification: true,   // raise on the Notification hook
+  },
+  // Custom command triggers (v0.10). Each entry maps a regex against the Bash
+  // command Claude runs to a brief presence frame, generalizing ship-detection.
+  // e.g. { "match": "npm (run )?test", "details": "Running tests in {project}" }
+  triggers: [],
+  // How long (seconds) a matched trigger frame stays up after the command ran.
+  triggerFrameSec: 20,
   // `claude-rpc badge --gist` records id+owner here after a successful
   // first publish so subsequent publishes UPDATE the same gist (the raw
   // URL in your README stays stable). filename is the file inside the
@@ -131,6 +165,8 @@ export const DEFAULT_CONFIG = {
           { details: "{allFreshTokensFmt} fresh tokens",       state: "{allCachePctLabel}",                         requires: ["allCachePctLabel"] },
           { details: "Code churn · {linesAddedFmt} added",     state: "{linesNetFmt} net · {topLanguage}",            requires: ["topLanguage"] },
           { details: "Cost · {todayCostFmt} today",            state: "{allCostFmt} all-time",                        requires: ["allCost"] },
+          { details: "Daily goal",                             state: "{goalLabel}",                                  requires: ["goalLabel"] },
+          { details: "Monthly budget",                         state: "{budgetLabel}",                                requires: ["budgetLabel"] },
         ],
       },
     },

package/src/format.js

@@ -303,6 +303,38 @@ export function buildVars(state, config, aggregate) {
   // Per-project cost for the current cwd's project.
   const projectCost = projectStats?.cost || 0;
 
+  // Goals (v0.10) — daily/weekly targets → progress label + hit flag.
+  const goalsCfg = config?.goals || {};
+  const todayHoursNum = (today.activeMs || 0) / 3_600_000;
+  const weekHoursNum = (thisWeek.activeMs || 0) / 3_600_000;
+  const pctOf = (cur, target) => (target > 0 ? Math.min(999, Math.round((cur / target) * 100)) : 0);
+  const goalDailyHoursPct = pctOf(todayHoursNum, goalsCfg.dailyHours || 0);
+  const goalDailyPromptsPct = pctOf(today.userMessages || 0, goalsCfg.dailyPrompts || 0);
+  const goalWeeklyHoursPct = pctOf(weekHoursNum, goalsCfg.weeklyHours || 0);
+  let goalLabel = '', goalHit = 0;
+  if ((goalsCfg.dailyHours || 0) > 0) {
+    goalLabel = `${fmtHours(today.activeMs || 0)} / ${goalsCfg.dailyHours}h · ${goalDailyHoursPct}%`;
+    goalHit = goalDailyHoursPct >= 100 ? 1 : 0;
+  } else if ((goalsCfg.dailyPrompts || 0) > 0) {
+    goalLabel = `${today.userMessages || 0} / ${goalsCfg.dailyPrompts} prompts · ${goalDailyPromptsPct}%`;
+    goalHit = goalDailyPromptsPct >= 100 ? 1 : 0;
+  } else if ((goalsCfg.weeklyHours || 0) > 0) {
+    goalLabel = `${fmtHours(thisWeek.activeMs || 0)} / ${goalsCfg.weeklyHours}h this week · ${goalWeeklyHoursPct}%`;
+    goalHit = goalWeeklyHoursPct >= 100 ? 1 : 0;
+  }
+
+  // Monthly cost budget (v0.10) — month-to-date spend vs budget.
+  const budgetCfg = config?.budget || {};
+  const monthlyBudget = budgetCfg.monthly || 0;
+  const monthPrefix = dayKey(Date.now()).slice(0, 7); // YYYY-MM
+  let mtdCost = 0;
+  for (const [k, d] of Object.entries(agg.byDay || {})) {
+    if (k.startsWith(monthPrefix)) mtdCost += d.cost || 0;
+  }
+  const budgetPct = monthlyBudget > 0 ? Math.round((mtdCost / monthlyBudget) * 100) : 0;
+  const budgetWarn = monthlyBudget > 0 && budgetPct >= (budgetCfg.warnAtPct || 80) ? 1 : 0;
+  const budgetLabel = monthlyBudget > 0 ? `${fmtCost(mtdCost)} / ${fmtCost(monthlyBudget)} · ${budgetPct}%` : '';
+
   // Weekday name from today's date.
   const weekdayLabel = WEEKDAY_NAMES[new Date().getDay()];
 
@@ -673,6 +705,17 @@ export function buildVars(state, config, aggregate) {
     projectCost,
     projectCostFmt: fmtCost(projectCost),
 
+    // ── Goals & budget (v0.10) ──────────────────────────────────
+    goalLabel,
+    goalHit,
+    goalDailyHoursPct,
+    goalDailyPromptsPct,
+    goalWeeklyHoursPct,
+    budgetLabel,
+    budgetPct,
+    budgetWarn,
+    budgetMtdFmt: fmtCost(mtdCost),
+
     // ── Time-of-day / weekday ───────────────────────────────────
     weekdayLabel,
     startTimeLabel: todayStartLabel,
@@ -847,6 +890,38 @@ export function applyShipped(state, cfg = {}) {
   return { ...state, status: 'shipped' };
 }
 
+// Overlay a custom-trigger frame when a recent Bash command matches a
+// user-defined pattern (config.triggers: [{ match, details, state }]). Called
+// by the daemon AFTER applyIdle/applyShipped — never overrides stale or the
+// shipped celebration. Window = triggerFrameSec (default 20s) from the command.
+// Returns a new state with status:'trigger' + _triggerFrame, or the input.
+export function applyTrigger(state, cfg = {}) {
+  const triggers = Array.isArray(cfg.triggers) ? cfg.triggers : [];
+  if (!triggers.length) return state;
+  if (state.status === 'stale' || state.status === 'shipped') return state;
+  const cmd = state.lastBashCommand || '';
+  if (!cmd) return state;
+  const windowMs = Math.max(3_000, (cfg.triggerFrameSec ?? 20) * 1000);
+  if (Date.now() - (state.lastBashAt || 0) > windowMs) return state;
+  for (const t of triggers) {
+    if (!t || !t.match) continue;
+    let re;
+    try { re = new RegExp(t.match, 'i'); } catch { continue; }
+    if (re.test(cmd)) {
+      return {
+        ...state,
+        status: 'trigger',
+        _triggerFrame: {
+          details: t.details || '{statusVerbose} in {project}',
+          state: t.state || '',
+          largeImageText: t.largeImageText || null,
+        },
+      };
+    }
+  }
+  return state;
+}
+
 // True when `requires` (string or array of strings) all resolve to non-zero / non-empty.
 export function framePasses(frame, vars) {
   const req = frame.requires;

package/src/hook.js

@@ -106,6 +106,12 @@ export function processHookEvent(event, input = {}) {
         s.lastActivity = now;
         s.claudeClosed = false;
         if (!s.sessionStart) s.sessionStart = now;
+        // Remember the running Bash command so the daemon can match custom
+        // triggers (config.triggers) against it for a brief overlay frame.
+        if (toolName === 'Bash' && toolInput.command) {
+          s.lastBashCommand = String(toolInput.command).slice(0, 500);
+          s.lastBashAt = now;
+        }
         if (file && (toolName === 'Read' || toolName === 'NotebookEdit')) {
           s.filesOpened = pushUnique(s.filesOpened, file);
           if (toolName === 'Read') s.filesRead = pushUnique(s.filesRead, file);

package/src/mcp.js

@@ -0,0 +1,143 @@
+// MCP server mode — exposes your own Claude Code stats as MCP tools so you can
+// ask Claude, mid-session, "how long have I worked today?" / "what's my top
+// file this week?" / "am I over budget?". Minimal newline-delimited JSON-RPC
+// over stdio (no SDK dep). Wire it into Claude Code as an MCP server:
+//   claude mcp add claude-rpc -- claude-rpc mcp
+//
+// The tool HANDLERS are pure functions of an aggregate, so they're unit-tested
+// without standing up the transport.
+
+import { readAggregate } from './scanner.js';
+import { buildVars } from './format.js';
+import { readState } from './state.js';
+import { loadConfig } from './config.js';
+import { VERSION } from './version.js';
+
+function fmtH(ms) { const h = (ms || 0) / 3_600_000; return h < 1 ? `${Math.round(h * 60)}m` : `${h.toFixed(1)}h`; }
+function fmtN(n) {
+  if (!n) return '0';
+  if (n < 1000) return String(Math.round(n));
+  if (n < 1e6) return `${(n / 1e3).toFixed(1)}k`;
+  if (n < 1e9) return `${(n / 1e6).toFixed(2)}M`;
+  return `${(n / 1e9).toFixed(2)}B`;
+}
+
+// ── Tool handlers — pure(aggregate) → string. Exported for tests. ──────────
+export const TOOLS = {
+  get_lifetime_stats: {
+    description: 'Overall all-time Claude Code stats: active hours, sessions, current/longest streak, total tokens, estimated cost, top language.',
+    handler(agg) {
+      const tokens = (agg.inputTokens || 0) + (agg.outputTokens || 0) + (agg.cacheReadTokens || 0) + (agg.cacheWriteTokens || 0);
+      const lang = Object.entries(agg.languages || {}).sort((a, b) => (b[1].edits || 0) - (a[1].edits || 0))[0];
+      return [
+        `Active time:   ${fmtH(agg.activeMs)}`,
+        `Sessions:      ${fmtN(agg.sessions || 0)}`,
+        `Streak:        ${agg.streak || 0} days (best ${agg.longestStreak || 0})`,
+        `Prompts:       ${fmtN(agg.userMessages || 0)}`,
+        `Tokens:        ${fmtN(tokens)}`,
+        `Est. cost:     $${(agg.estimatedCost || 0).toFixed(2)}`,
+        `Top language:  ${lang ? `${lang[0]} (${fmtN(lang[1].edits)} edits)` : '—'}`,
+        `Since:         day ${agg.daysSinceFirst || 0}`,
+      ].join('\n');
+    },
+  },
+  get_today: {
+    description: "Today's Claude Code activity: active hours, prompts, tool calls, tokens, estimated cost.",
+    handler(agg) {
+      const today = (agg.byDay || {})[new Date().toISOString().slice(0, 10)] || {};
+      const tokens = (today.inputTokens || 0) + (today.outputTokens || 0) + (today.cacheReadTokens || 0) + (today.cacheWriteTokens || 0);
+      return [
+        `Active time:  ${fmtH(today.activeMs)}`,
+        `Prompts:      ${today.userMessages || 0}`,
+        `Tool calls:   ${today.toolCalls || 0}`,
+        `Tokens:       ${fmtN(tokens)}`,
+        `Est. cost:    $${(today.cost || 0).toFixed(2)}`,
+      ].join('\n');
+    },
+  },
+  get_top_files: {
+    description: 'Most-edited files all-time, with edit counts and how long since each was last touched.',
+    handler(agg) {
+      const list = (agg.topEditedFiles || []).slice(0, 10);
+      if (!list.length) return 'No edited files recorded yet.';
+      return list.map((f, i) => {
+        const name = String(f.path || '').replace(/\\/g, '/').split('/').pop();
+        const age = f.daysSinceLastEdit == null ? '' : f.daysSinceLastEdit === 0 ? ' · today' : ` · ${f.daysSinceLastEdit}d ago`;
+        return `${i + 1}. ${name} — ${f.count} edits${age}`;
+      }).join('\n');
+    },
+  },
+  get_model_split: {
+    description: 'Per-model breakdown of spend, tokens, and turns across all of Claude Code history.',
+    handler(agg) {
+      const split = agg.modelSplit || [];
+      if (!split.length) return 'No model usage recorded yet.';
+      return split.map((m) => `${m.model}: $${(m.cost || 0).toFixed(2)} (${Math.round((m.costPct || 0) * 100)}%) · ${fmtN(m.tokens)} tokens · ${m.turns} turns`).join('\n');
+    },
+  },
+};
+
+// Build a tools/list payload from the registry.
+export function toolList() {
+  return Object.entries(TOOLS).map(([name, t]) => ({
+    name,
+    description: t.description,
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  }));
+}
+
+// Dispatch a tools/call by name. Reads a fresh aggregate per call (cheap).
+export function callTool(name, getAgg = readAggregate) {
+  const t = TOOLS[name];
+  if (!t) throw new Error(`unknown tool: ${name}`);
+  const agg = getAgg() || {};
+  return t.handler(agg);
+}
+
+// ── stdio JSON-RPC transport (newline-delimited) ──────────────────────────
+export function runMcpServer({ input = process.stdin, output = process.stdout } = {}) {
+  let buf = '';
+  const send = (msg) => output.write(JSON.stringify(msg) + '\n');
+  const reply = (id, result) => send({ jsonrpc: '2.0', id, result });
+  const replyErr = (id, code, message) => send({ jsonrpc: '2.0', id, error: { code, message } });
+
+  function handle(msg) {
+    const { id, method, params } = msg;
+    if (method === 'initialize') {
+      return reply(id, {
+        protocolVersion: '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'claude-rpc', version: VERSION },
+      });
+    }
+    if (method === 'notifications/initialized' || method === 'notifications/cancelled') return; // notifications: no reply
+    if (method === 'tools/list') return reply(id, { tools: toolList() });
+    if (method === 'tools/call') {
+      const name = params?.name;
+      try {
+        const text = callTool(name);
+        return reply(id, { content: [{ type: 'text', text }], isError: false });
+      } catch (e) {
+        return reply(id, { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true });
+      }
+    }
+    if (method === 'ping') return reply(id, {});
+    if (id !== undefined) replyErr(id, -32601, `method not found: ${method}`);
+  }
+
+  input.setEncoding('utf8');
+  input.on('data', (chunk) => {
+    buf += chunk;
+    let nl;
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (!line) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { continue; }
+      try { handle(msg); } catch (e) { process.stderr.write(`mcp handler error: ${e.message}\n`); }
+    }
+  });
+  input.on('end', () => process.exit(0));
+  process.stderr.write(`claude-rpc MCP server v${VERSION} ready (stdio)\n`);
+}