claude-rpc 0.20.1 → 0.20.2

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.2",
   "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

@@ -12,22 +12,57 @@ if (process.platform === 'win32' && process.stdout.isTTY) {
 }
 import { DAEMON_SCRIPT, PID_PATH, 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';
+
+// ── 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';
@@ -1972,6 +2007,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':

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;
 }
@@ -721,10 +729,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 +823,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.2';
 
 function readPkgVersion() {
   try {