claude-rpc 0.20.1 → 0.20.3

package/README.md

@@ -1,16 +1,21 @@
 <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" />
+<img src="docs/header.svg" width="820" alt="claude-rpc — Discord Rich Presence for Claude Code: live model, project, tokens, and lifetime stats, driven by the hooks Claude Code already fires. Install with: npx claude-rpc setup" />
 
-# claude-rpc
+<br/><br/>
 
-**Discord Rich Presence (RPC) for [Claude Code](https://claude.com/claude-code).**
-Your live model, project, current tool, tokens, and lifetime stats — in your Discord profile. Driven by the hooks Claude Code already fires. Zero polling between sessions.
+<img src="https://cdn.qualit.ly/clawd-working-building.gif" width="104" alt="working" />
+<img src="https://cdn.qualit.ly/clawd-working-typing.gif" width="104" alt="thinking" />
+<img src="https://cdn.qualit.ly/clawd-notification.gif" width="104" alt="waiting on you" />
+<img src="https://cdn.qualit.ly/clawd-sleeping.gif" width="104" alt="idle" />
 
-**→ [claude-rpc.vercel.app](https://claude-rpc.vercel.app)** — what it looks like, in one page.
+<sub>the card's live states — <b>working</b> · <b>thinking</b> · <b>waiting</b> · <b>idle</b></sub>
+
+<br/>
+
+**Discord Rich Presence for [Claude Code](https://claude.com/claude-code)** — your live model, project, tokens, and lifetime stats, driven by the hooks Claude Code already fires.
+
+**[claude-rpc.vercel.app →](https://claude-rpc.vercel.app)** — see it in one page.
 
 [![community · sessions](https://claude-rpc-totals.claude-rpc.workers.dev/sessions.svg)](#community-totals) &nbsp; [![community · tokens](https://claude-rpc-totals.claude-rpc.workers.dev/tokens.svg)](#community-totals)
 
@@ -144,7 +149,11 @@ claude-rpc card  --range year                 --out year-on-claude.svg
 ```
 
 <div align="center">
-  <img src="site/examples/year-on-claude.svg" width="560" alt="Year-on-claude card — hours, prompts, tokens, lines, cost, daily activity strip" />
+  <img src="site/examples/week-on-claude.svg"  width="270" alt="Week-on-claude summary card" />
+  <img src="site/examples/month-on-claude.svg" width="270" alt="Month-on-claude summary card" />
+  <img src="site/examples/year-on-claude.svg"  width="270" alt="Year-on-claude summary card — hours, prompts, tokens, lines, cost, daily activity strip" />
+  <br/>
+  <sub><code>card --range week · month · year</code> (also <code>all</code>) — live at <code>/api/card.svg</code> while the daemon's up</sub>
 </div>
 
 `badge --gist` writes the SVG to your own GitHub gist (creates one on first run, updates it after — id remembered in `config.json`). The URL printed back is README-ready and updates every time you re-run the command. Uses `gh` if available, else `GH_TOKEN` with `gist` scope.
@@ -173,21 +182,9 @@ For a complete account of the sensitive things claude-rpc does — startup persi
 
 ## three pieces, glued by json files
 
-```
-   Claude Code                                          Discord desktop
-        │                                                     ▲
-        │ lifecycle event (stdin JSON)                        │ IPC frame
-        ▼                                                     │
-   ┌──────────┐    state.json    ┌──────────┐                 │
-   │ hook.js  │ ───────────────▶ │ daemon.js│ ────────────────┘
-   └──────────┘                  └──────────┘
-                                       ▲
-                                       │ aggregate.json
-                                       │
-                                ┌────────────┐
-                                │ scanner.js │ ◀── ~/.claude/projects/*.jsonl
-                                └────────────┘
-```
+<div align="center">
+  <img src="docs/architecture.svg" width="760" alt="Architecture: Claude Code fires a lifecycle event (stdin JSON) into hook.js, which writes state.json; daemon.js reads it and pushes an IPC frame to the Discord desktop client. scanner.js reads the ~/.claude/projects transcripts and feeds aggregate.json into daemon.js." />
+</div>
 
 No database, no message bus, no background polling when Claude Code isn't running. State on disk you can `cat` and `jq`. **Zero runtime dependencies** — even the Discord Rich Presence IPC client is hand-rolled (`src/discord-ipc.js`).
 
@@ -263,6 +260,13 @@ The full default config is in [`src/default-config.js`](src/default-config.js)
 
 ## commands
 
+`claude-rpc --help` lists them all — and after `setup` you rarely need any.
+
+<details>
+<summary><b>full command reference</b></summary>
+
+<br/>
+
 | Command          | What it does |
 | ---------------- | ------------ |
 | `setup`          | Install Claude Code hooks (test-fires one synthetic SessionStart to prove the pipe works) |
@@ -295,19 +299,28 @@ The full default config is in [`src/default-config.js`](src/default-config.js)
 
 Exit codes: `0` ok · `1` user error · `2` system error · `3` wrong state. `--version` and `--help` work as expected.
 
+</details>
+
 ## troubleshooting
 
-**First step is always `claude-rpc doctor`.** It checks Node version, hook registration, daemon liveness, Discord IPC connection, aggregate freshness, and privacy resolution — with a one-line fix hint per failure.
+**First step is always `claude-rpc doctor`** — it checks Node, hook registration, daemon liveness, Discord IPC, aggregate freshness, and privacy resolution, with a one-line fix hint per failure.
+
+<details>
+<summary><b>common issues</b></summary>
+
+<br/>
 
 - **Discord doesn't show anything.** Discord *desktop* must be running. The browser client doesn't expose the local IPC bridge. `claude-rpc tail` shows what the daemon is actually doing.
 - **Hooks don't fire.** `claude-rpc setup` re-registers them and now test-fires a synthetic `SessionStart` end-to-end, so a broken hook command surfaces immediately. Restart Claude Code afterwards so it re-reads its hook config.
 - **Config error.** Bad JSON in `config.json` no longer crashes anything — the daemon logs one line and falls back to baked defaults. `claude-rpc tail` shows the parse error verbatim.
 - **Old binary path baked into hooks.** Common after manual exe replacement. `claude-rpc setup` rewrites hook entries to point at the canonical install location.
 
+</details>
+
 ## development
 
 ```sh
-npm test                  # 270+ tests, ~2s
+npm test                  # 430+ tests, ~2s
 npm run lint              # eslint over src + test
 npm run start             # run daemon in foreground
 npm run serve             # web dashboard against your real data
@@ -315,9 +328,7 @@ npm run dashboard         # Electron settings GUI (dev mode)
 npm run build:exe         # SEA single-file binary for the current OS
 ```
 
-Tests are `node --test` with zero deps. The CI pipeline ([release.yml](.github/workflows/release.yml)) runs the suite (plus the Cloudflare Worker's own tests) across Node 18/20/22 and gates the matrix build and the npm publish behind it. Every pure/logic module in `src/*.js` is unit-tested, including the MCP transport and the SVG renderers; the long-running daemon, the TUI, and the CLI dispatcher are covered by integration and manual smoke testing rather than unit tests.
-
-Where the project is headed (and what it will deliberately never do) lives in [`ROADMAP.md`](ROADMAP.md).
+Tests are `node --test`, zero deps; CI ([release.yml](.github/workflows/release.yml)) runs the suite (+ the Worker's) across Node 18/20/22 and gates the matrix build and npm publish. Where the project's headed (and what it'll deliberately never do): [`ROADMAP.md`](ROADMAP.md).
 
 ## license
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-rpc",
-  "version": "0.20.1",
+  "version": "0.20.3",
   "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/cli.js

@@ -10,24 +10,59 @@ import process from 'node:process';
 if (process.platform === 'win32' && process.stdout.isTTY) {
   try { spawnSync('chcp.com', ['65001'], { stdio: 'ignore', windowsHide: true }); } catch { /* chcp absent (Wine, custom shell) — accept whatever code page is set */ }
 }
-import { DAEMON_SCRIPT, PID_PATH, STATE_PATH, LOG_PATH, AGGREGATE_PATH, CONFIG_PATH, IS_PACKAGED, IS_NPX, EXE_PATH } from './paths.js';
+import { DAEMON_SCRIPT, STATE_PATH, LOG_PATH, AGGREGATE_PATH, CONFIG_PATH, IS_PACKAGED, IS_NPX, EXE_PATH } from './paths.js';
 import { readActiveState } from './state.js';
-import { buildVars, fillTemplate, humanProject, humanTool, applyIdle, framePasses, fmtNum } from './format.js';
-import { scan, readAggregate, findLiveSessions, dayKey, weekKey } from './scanner.js';
-import { weekGrid } from './week.js';
 import { runHookCli } from './hook.js';
-import { install as runInstall, uninstall as runUninstall, isInstalled, migrateConfig, installHooks, ensureCanonicalExe, installMcp, uninstallMcp, setupOutro } from './install.js';
-import { startTui } from './tui.js';
-import { generateInsights } from './insights.js';
-import { maybeNudge, pickTodayMilestone } from './nudge.js';
-import { badgeSvg } from './badge.js';
-import { fmtCost } from './pricing.js';
-import { addPrivateCwd, removePrivateCwd, listPrivateCwds, resolveVisibility } from './privacy.js';
 import { parseDuration, setPause, clearPause, pauseUntil } from './pause.js';
-import { readUsageCache, fetchUsage, writeUsageCache, fmtResetTime, fmtResetDay } from './usage.js';
 import { loadConfig, hasUserConfig } from './config.js';
-import { spawnDaemonDetached } from './ensure-daemon.js';
-import * as lb from './leaderboard.js';
+import { spawnDaemonDetached, daemonAlive } from './ensure-daemon.js';
+
+// ── Lazy-loaded heavy module graph ───────────────────────────────────────────
+// format→scanner→pricing→languages→git→usage (plus install/tui/insights/nudge/
+// badge/privacy/leaderboard) is ~60ms of module-load that the fast-exit commands
+// (--version, --help, start, stop, restart) never touch. We declare the bindings
+// here and fill them via loadStats() only for commands that actually fan out into
+// the stats/format/install code, so daemon-control and version stay near-instant.
+// (The repo already lazy-imports cold deps like doctor.js/card.js/mcp.js inside
+// their handlers — this just extends that to the graph the main switch needs.)
+let buildVars, fillTemplate, humanProject, humanTool, applyIdle, framePasses, fmtNum;
+let scan, readAggregate, findLiveSessions, dayKey, weekKey;
+let weekGrid;
+let runInstall, runUninstall, isInstalled, migrateConfig, installHooks, ensureCanonicalExe, installMcp, uninstallMcp, setupOutro;
+let startTui;
+let generateInsights;
+let maybeNudge, pickTodayMilestone;
+let badgeSvg;
+let fmtCost;
+let addPrivateCwd, removePrivateCwd, listPrivateCwds, resolveVisibility;
+let readUsageCache, fetchUsage, writeUsageCache, fmtResetTime, fmtResetDay;
+let lb;
+
+let statsLoaded = false;
+async function loadStats() {
+  if (statsLoaded) return;
+  // Load the graph concurrently — these are all leaf-ish modules with no
+  // ordering dependency, so Promise.all beats a sequential import chain.
+  const [fmt, scn, wk, inst, tui, ins, ndg, bdg, prc, priv, usg, leaderboard] = await Promise.all([
+    import('./format.js'), import('./scanner.js'), import('./week.js'),
+    import('./install.js'), import('./tui.js'), import('./insights.js'),
+    import('./nudge.js'), import('./badge.js'), import('./pricing.js'),
+    import('./privacy.js'), import('./usage.js'), import('./leaderboard.js'),
+  ]);
+  ({ buildVars, fillTemplate, humanProject, humanTool, applyIdle, framePasses, fmtNum } = fmt);
+  ({ scan, readAggregate, findLiveSessions, dayKey, weekKey } = scn);
+  ({ weekGrid } = wk);
+  ({ install: runInstall, uninstall: runUninstall, isInstalled, migrateConfig, installHooks, ensureCanonicalExe, installMcp, uninstallMcp, setupOutro } = inst);
+  ({ startTui } = tui);
+  ({ generateInsights } = ins);
+  ({ maybeNudge, pickTodayMilestone } = ndg);
+  ({ badgeSvg } = bdg);
+  ({ fmtCost } = prc);
+  ({ addPrivateCwd, removePrivateCwd, listPrivateCwds, resolveVisibility } = priv);
+  ({ readUsageCache, fetchUsage, writeUsageCache, fmtResetTime, fmtResetDay } = usg);
+  lb = leaderboard;
+  statsLoaded = true;
+}
 import { VERSION } from './version.js';
 import { fail, tailLines, heat, sparkline, fmtDelta, topPercentile, EX_USER_ERROR, EX_BAD_STATE, EX_SYS_ERROR } from './ui.js';
 import { randomUUID } from 'node:crypto';
@@ -81,18 +116,8 @@ function takeValue(v, flag) {
   return v;
 }
 
-function isAlive(pid) {
-  try { process.kill(pid, 0); return true; } catch { return false; }
-}
-
-function daemonPid() {
-  if (!existsSync(PID_PATH)) return null;
-  const pid = Number(readFileSync(PID_PATH, 'utf8'));
-  return pid && isAlive(pid) ? pid : null;
-}
-
 function startDaemon({ quiet = false } = {}) {
-  const pid = daemonPid();
+  const pid = daemonAlive();
   if (pid) {
     if (!quiet) console.log(`  ${c.yellow}!${c.reset}  ${'daemon running'.padEnd(16)}${c.dim}already up (pid ${pid}) · bounce it with ${c.reset}${c.cyan}claude-rpc restart${c.reset}`);
     return false;
@@ -119,7 +144,7 @@ async function confirmDaemonUp({ timeoutMs = 3000, intervalMs = 100 } = {}) {
   const deadline = Date.now() + timeoutMs;
   for (;;) {
     await new Promise((r) => setTimeout(r, intervalMs));
-    if (daemonPid()) {
+    if (daemonAlive()) {
       console.log(`  ${c.green}✓${c.reset}  ${'daemon confirmed'.padEnd(16)}${c.dim}up — connecting to Discord${c.reset}`);
       return true;
     }
@@ -131,7 +156,7 @@ async function confirmDaemonUp({ timeoutMs = 3000, intervalMs = 100 } = {}) {
 }
 
 function stopDaemon({ quiet = false } = {}) {
-  const pid = daemonPid();
+  const pid = daemonAlive();
   if (!pid) { if (!quiet) console.log(`  ${c.cyan}·${c.reset}  daemon not running`); return false; }
   try {
     process.kill(pid, 'SIGTERM');
@@ -151,9 +176,9 @@ function restartDaemon() {
   // one exited. Give up after ~3s, force-kill the wedged pid, and start anyway.
   const deadline = Date.now() + 3000;
   const tick = () => {
-    if (!daemonPid()) { startDaemon(); return; }
+    if (!daemonAlive()) { startDaemon(); return; }
     if (Date.now() >= deadline) {
-      const pid = daemonPid();
+      const pid = daemonAlive();
       if (pid) { try { process.kill(pid, 'SIGKILL'); } catch { /* already gone */ } }
       startDaemon();
       return;
@@ -376,7 +401,7 @@ function showStatus() {
   state.liveSessions = live;
   state.usage = readUsageCache();
   const vars = buildVars(state, config, aggregate);
-  const pid = daemonPid();
+  const pid = daemonAlive();
 
   console.log('');
   console.log(`  ${c.bold}${c.magenta}◆ Claude RPC${c.reset}  ${c.dim}— Discord Rich Presence for Claude Code${c.reset}`);
@@ -1828,7 +1853,7 @@ function tailLog() {
 function overview() {
   const setUp = hasUserConfig();
   const cfg = loadConfig();
-  const pid = daemonPid();
+  const pid = daemonAlive();
 
   console.log('');
   console.log(`  ${c.bold}${c.magenta}◆ claude-rpc${c.reset}  ${c.dim}v${VERSION} — Discord Rich Presence for Claude Code${c.reset}`);
@@ -1972,6 +1997,12 @@ process.on('unhandledRejection', (e) => {
 // ESM (dev) and CommonJS (esbuild → SEA bundle) — CJS doesn't allow
 // top-level await.
 (async () => {
+  // Fast-exit commands touch none of the lazy stats/format/install graph, so
+  // skip the module load and keep them instant. Everything else loads it once
+  // up front, which makes every binding available to the handlers below exactly
+  // as before. (daemon/serve/wrapped/hook only dynamic-import their own module.)
+  const FAST_PATHS = new Set(['--version', '-V', '-v', '--help', '-h', 'help', 'start', 'stop', 'restart', 'hook', 'daemon', 'serve', 'wrapped']);
+  if (!FAST_PATHS.has(cmd)) await loadStats();
   switch (cmd) {
     case '--version':
     case '-V':
@@ -2004,7 +2035,7 @@ process.on('unhandledRejection', (e) => {
           // console, the grandchild node allocates a fresh one, and Windows 11
           // pops it as a visible Windows Terminal window whose closure kills
           // the daemon.
-          if (!daemonPid()) {
+          if (!daemonAlive()) {
             let script = null;
             try {
               const r = spawnSync('npm', ['root', '-g'], {
@@ -2024,7 +2055,7 @@ process.on('unhandledRejection', (e) => {
             child.unref();
             console.log(`  ${c.green}✓${c.reset}  ${'daemon launched'.padEnd(16)}${c.dim}pid ${c.reset}${c.cyan}${child.pid}${c.reset}${c.dim} · log ${shortPath(LOG_PATH)}${c.reset}`);
           } else {
-            console.log(`  ${c.cyan}·${c.reset}  ${'daemon running'.padEnd(16)}${c.dim}pid ${daemonPid()}${c.reset}`);
+            console.log(`  ${c.cyan}·${c.reset}  ${'daemon running'.padEnd(16)}${c.dim}pid ${daemonAlive()}${c.reset}`);
           }
         } else {
           startDaemon();

package/src/format.js

@@ -870,7 +870,9 @@ export function applyIdle(state, cfg = {}) {
   if (state.status === 'notification') {
     const notifAge = now - (state.lastNotification || 0);
     if (notifAge <= notificationMs) return state;
-    state = { ...state, status: 'idle' };
+    // Going idle after a notification — wipe the current-activity slots so idle
+    // frames don't render stale file/tool names (same as the idle path below).
+    state = { ...state, status: 'idle', currentTool: null, currentFile: null, filesOpened: [], filesEdited: [], filesRead: [] };
   }
 
   // Truly dormant: no live transcripts AND local state is old → stale.

package/src/scanner.js

@@ -439,8 +439,15 @@ function parseChunkInto(text, summary, pstate) {
 // null) falls back to a from-scratch parse.
 export function parseTranscript(filePath, prev = null) {
   const st = statSync(filePath);
+  // Append only if this is the SAME file that grew: the current size must be
+  // >= the size at the last parse (mirrors readSessionTokens). The old check,
+  // `st.size >= prev._offset`, was too weak — a rewrite to a size between the
+  // consumed offset and the prior file size would wrongly append onto stale
+  // counts (the leading bytes are now different content), silently corrupting
+  // lifetime stats. A cache entry predating _size has no size to compare, so it
+  // falls back to a full re-parse (which then stamps _size going forward).
   const canAppend = !!(prev && prev._parse && typeof prev._offset === 'number'
-    && st.size >= prev._offset);
+    && typeof prev._size === 'number' && st.size >= prev._size);
   const summary = canAppend ? structuredClone(prev) : blankTranscriptSummary();
   const pstate = canAppend
     ? { recentIds: (prev._parse.recentIds || []).slice(), lastRec: prev._parse.lastRec || null }
@@ -481,6 +488,7 @@ export function parseTranscript(filePath, prev = null) {
     // else: a partial line mid-write — leave it for the next (append) read.
   }
   summary._offset = offset;
+  summary._size = st.size; // file size at this parse — guards the append fast-path above
   summary._parse = { recentIds: pstate.recentIds, lastRec: pstate.lastRec };
   return summary;
 }
@@ -691,18 +699,22 @@ function writeCache(cache) {
 // Per-day notification counts come from a hook-side append log, since
 // transcripts don't carry Notification events reliably.
 function readNotificationsByDay() {
-  if (!existsSync(EVENTS_LOG_PATH)) return {};
   const out = {};
-  try {
-    const raw = readFileSync(EVENTS_LOG_PATH, 'utf8');
-    for (const line of raw.split('\n')) {
-      if (!line) continue;
-      const e = safeJson(line);
-      if (!e || e.type !== 'notification' || !e.ts) continue;
-      const k = dayKey(e.ts);
-      out[k] = (out[k] || 0) + 1;
-    }
-  } catch { /* events log unreadable/truncated — return whatever we got, the aggregate will just under-count notifications */ }
+  // The hook rotates events.jsonl to `.1` at 5MB; read both (oldest first) so a
+  // rotation doesn't silently drop a day's notification counts.
+  for (const path of [EVENTS_LOG_PATH + '.1', EVENTS_LOG_PATH]) {
+    if (!existsSync(path)) continue;
+    try {
+      const raw = readFileSync(path, 'utf8');
+      for (const line of raw.split('\n')) {
+        if (!line) continue;
+        const e = safeJson(line);
+        if (!e || e.type !== 'notification' || !e.ts) continue;
+        const k = dayKey(e.ts);
+        out[k] = (out[k] || 0) + 1;
+      }
+    } catch { /* a rotation file unreadable/truncated — count what we can */ }
+  }
   return out;
 }
 
@@ -721,10 +733,11 @@ export function readAggregate() {
 
 export { dayKey, weekKey, hourKey };
 
-function aggregateFrom(cache) {
+export function aggregateFrom(cache) {
   const agg = {
     sessions: 0,
     subagentRuns: 0,
+    subagentActiveMs: 0,
     inputTokens: 0,
     outputTokens: 0,
     cacheReadTokens: 0,
@@ -814,6 +827,15 @@ function aggregateFrom(cache) {
     }
     if (isSub) {
       agg.subagentRuns += 1;
+      // Subagent active time is tracked separately and deliberately NOT folded
+      // into agg.activeMs. A subagent's wall-time overlaps its parent session
+      // (and parallel subagents overlap each other), and gaps >=5min are already
+      // excluded from the parent's activeMs (see ACTIVE_GAP_CAP_MS) — so summing
+      // the scalar would double-count short subagents. agg.activeMs stays an
+      // interactive-session measure; subagentActiveMs exposes delegated work as
+      // its own honest number. A single unified figure would need interval-union
+      // across parent+subagents, not scalar sums.
+      agg.subagentActiveMs += summary.activeMs || 0;
       // Subagents still contribute tokens/tools/lines/cost to per-day/week/hour buckets.
       const mergeSubBuckets = (srcMap, destMap) => {
         for (const [k, src] of Object.entries(srcMap || {})) {

package/src/version.js

@@ -11,7 +11,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ROOT } from './paths.js';
 
-const BAKED = '0.20.1';
+const BAKED = '0.20.3';
 
 function readPkgVersion() {
   try {