claude-rpc 0.24.1 → 1.0.2

package/README.md

@@ -193,7 +193,7 @@ claude-rpc community on           # explicit consent flow (upgraders / re-enable
 claude-rpc community report       # one-shot manual flush (testing)
 ```
 
-Each report sends only: a `sessionsDelta`, a `tokensDelta`, the claude-rpc version, OS family (`linux`/`darwin`/`win32`), and the anonymous UUID v4. No prompts, paths, models, repos, costs, usernames, or hostnames — the Worker's [`validateReport`](worker/src/index.js) is the schema of record. The full Worker source is in this repo so the privacy claim is auditable.
+Each report sends only: a `sessionsDelta`, a `tokensDelta`, the claude-rpc version, OS family (`linux`/`darwin`/`win32`), and the anonymous UUID v4. No prompts, paths, models, repos, costs, usernames, or hostnames — the Worker's [`validateReport`](worker/src/index.js) is the schema of record. The full Worker source is in this repo so the privacy claim is auditable. Every worker route — path, params, response — is documented in [`docs/WORKER-API.md`](docs/WORKER-API.md).
 
 For a complete account of the sensitive things claude-rpc does — startup persistence, hook injection, every outbound request, and the exact telemetry payload — see [`SECURITY.md`](SECURITY.md). It's also the reference for supply-chain scanner findings (Socket.dev et al.): the flagged persistence and hook-injection behaviors are inherent to the tool and documented there.
 
@@ -273,7 +273,7 @@ Frames have a `requires` field; the daemon skips a frame when any of its require
 }
 ```
 
-The full default config is in [`src/default-config.js`](src/default-config.js) — that's the canonical list of every key. ~140 template variables are available; `claude-rpc vars` is the source of truth.
+The full default config is in [`src/default-config.js`](src/default-config.js) — that's the canonical list of every key. Over 200 template variables are available; `claude-rpc vars` is the authoritative list.
 
 ## claude code plugin
 
@@ -330,6 +330,36 @@ Exit codes: `0` ok · `1` user error · `2` system error · `3` wrong state. `--
 
 </details>
 
+<details>
+<summary><b>complete removal</b></summary>
+
+<br/>
+
+`claude-rpc uninstall` removes everything that *respawns or registers* the tool:
+its hooks from `~/.claude/settings.json` (only its own — third-party hooks are
+left untouched) and the login-autostart entry (`systemd --user` unit on Linux,
+LaunchAgent on macOS, `HKCU\…\Run` value + `.vbs` shim on Windows). After it
+runs, nothing brings the daemon back.
+
+It deliberately **leaves your data in place**: `config.json` (under the per-OS
+config dir), the stats in `~/.claude-rpc/`, and the transient files in the temp
+dir (which clear on reboot anyway). Two things it does *not* touch, by design:
+
+- a daemon already running this session keeps running until `claude-rpc stop` or
+  reboot (the autostart-managed one is stopped; a manually `start`ed one isn't);
+- the MCP server, if you wired it — that's a separate `claude-rpc mcp uninstall`.
+
+For a clean wipe on macOS/Linux:
+
+```sh
+claude-rpc mcp uninstall   # only if you ran `mcp install`
+claude-rpc stop
+claude-rpc uninstall
+rm -rf ~/.claude-rpc        # stats; plus the per-OS config dir if you want it gone
+```
+
+</details>
+
 ## troubleshooting
 
 **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.
@@ -346,6 +376,39 @@ Exit codes: `0` ok · `1` user error · `2` system error · `3` wrong state. `--
 
 </details>
 
+## platform support
+
+**macOS and Linux are first-class.** The daemon reacts to on-disk changes with a
+directory watcher (`fs.watch` over FSEvents/inotify — instant) *and* an mtime
+poll as a lazy backstop, so an event is never missed. Login autostart is a
+per-user [`launchd` LaunchAgent](src/install.js) on macOS and a
+[`systemd --user` service](src/install.js) on Linux; both start the daemon at
+login without `sudo` and don't fight a manual `claude-rpc stop`.
+
+**Windows is supported** — grab the portable exe (no Node required), then
+`claude-rpc setup`. One caveat documented honestly: `fs.watch` on Windows drops
+events when a writer commits via atomic rename (which the state file, pause file,
+scanner, and settings GUI all do), so on Windows the **mtime poll is effectively
+the primary path** and runs an order of magnitude faster (every ~3s vs ~30s
+elsewhere) to compensate. It's a reliable fallback, not yet the native-watch
+confidence macOS/Linux get — closing that gap is on the [roadmap](ROADMAP.md).
+Autostart is an `HKCU\…\Run` entry launched through a windowless `.vbs` shim (no
+scheduled task, by design — see [`SECURITY.md`](SECURITY.md)).
+
+Everything else — the scanner, dashboards, cards, the worker client — is
+platform-neutral. CI runs the full suite on Node 18/20/22 and builds the macOS
+and Windows binaries every release.
+
+## versioning
+
+What's a stable contract and what's an internal detail you shouldn't build on:
+[`VERSIONING.md`](VERSIONING.md). Short version — the worker HTTP API, the CLI
+(commands, flags, exit codes), the `config.json` schema, the `claude-rpc vars`
+template variables, and the local data formats are stable and semver-governed;
+daemon internals, the scan cache, the worker's KV layout, and exact wording are
+not. The worker's HTTP surface is documented in
+[`docs/WORKER-API.md`](docs/WORKER-API.md).
+
 ## development
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-rpc",
-  "version": "0.24.1",
+  "version": "1.0.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/daemon.js

@@ -117,6 +117,15 @@ let lastSentHash = '';
 let lastSentAt = 0;       // ms of the last write ATTEMPT (success or fail → back off either way)
 let pendingSend = null;   // { kind, activity, hash, logMsg } coalesced during the gap; latest wins
 let flushTimer = null;
+// Timestamps (ms) of recent write ATTEMPTS (set + clear both hit Discord), for
+// the sliding-window rate cap below. The per-write gap alone leaves the daemon
+// riding Discord's ~5-per-20s SET_ACTIVITY ceiling — many triggers fire and a
+// 4s gap still permits 6 writes in some 20s windows, which makes Discord EMPTY
+// the presence (card → app name + bare timer). This bounds the COUNT per window
+// regardless of how many triggers fire. Deliberately NOT cleared by
+// resetTransmit (a scan/session/config refresh forces a re-render but must not
+// reset the rate budget, or those refreshes could burst us past the limit).
+let recentSends = [];
 // 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;
@@ -407,12 +416,24 @@ function pushPresence() {
 }
 
 // Minimum gap between Discord writes, read live so a config reload takes effect.
-// Floored at 2s as a sanity minimum; the 4s default keeps us under Discord's
-// ~5-per-20s SET_ACTIVITY limit (see default-config.minActivityGapMs).
+// Floored at 2s as a sanity minimum. The gap spaces consecutive writes; the
+// sliding-window cap below is what actually bounds writes-per-window so we stay
+// under Discord's ~5-per-20s SET_ACTIVITY limit (see default-config).
 function activityGapMs() {
   return Math.max(2000, config.minActivityGapMs || 4000);
 }
 
+// Sliding-window rate cap parameters, read live like the gap. Defaults to 4
+// writes per 20s — one under Discord's ~5-per-20s SET_ACTIVITY ceiling, so we
+// stay clear of it even if Discord counts its window inclusively or our clock
+// drifts. Floored so a bad config can't disable the protection entirely.
+function activityWindowMs() {
+  return Math.max(5000, config.activityWindowMs || 20000);
+}
+function maxActivityWrites() {
+  return Math.max(2, config.maxActivityWrites || 4);
+}
+
 // Sentinel for a clear — can never collide with a real activity hash, since
 // JSON.stringify of an activity object always begins with '{'.
 const CLEAR_HASH = 'cleared';
@@ -425,6 +446,7 @@ function transmit(kind, activity, logMsg) {
   const d = throttleDecision({
     hash, lastSentHash, lastSentAt,
     now: Date.now(), gapMs: activityGapMs(), flushPending: !!flushTimer,
+    recentSends, windowMs: activityWindowMs(), maxPerWindow: maxActivityWrites(),
   });
   if (d.action === 'skip') { pendingSend = null; return; }
   if (d.action === 'send') { doSend({ kind, activity, hash, logMsg }); return; }
@@ -451,6 +473,12 @@ function flushPendingSend() {
 // by the next push rather than being recorded as success and stranded.
 async function doSend({ kind, activity, hash, logMsg }) {
   lastSentAt = Date.now();
+  // Record the attempt and drop anything older than the window — this is the
+  // ledger throttleDecision reads to enforce the per-window cap. Counts every
+  // attempt (set AND clear) since both are SET_ACTIVITY writes to Discord.
+  recentSends.push(lastSentAt);
+  const cutoff = lastSentAt - activityWindowMs();
+  if (recentSends[0] <= cutoff) recentSends = recentSends.filter((t) => t > cutoff);
   try {
     if (kind === 'clear') await client.user.clearActivity();
     else await client.user.setActivity(activity);

package/src/default-config.js

@@ -28,6 +28,17 @@ export const DEFAULT_CONFIG = {
   // collapse to the latest and flush when the gap expires. 4s stays safely
   // under the limit; lower values risk Discord throttling the card.
   minActivityGapMs: 4000,
+  // Hard sliding-window cap on Discord writes, on top of minActivityGapMs. The
+  // gap alone only spaces *consecutive* writes — with a 4s gap a 20s window can
+  // still catch 6 writes (floor(20000/4000)+1) once several triggers (the
+  // rotation tick, a scan, a live-session change, a config reload) coincide,
+  // and that 6th write is what makes Discord EMPTY the presence (the card
+  // collapses to just the app name + elapsed timer, no details or art). This
+  // bounds the COUNT per window: no more than maxActivityWrites writes per
+  // activityWindowMs, whatever fires. Default 4-per-20s leaves a write of
+  // headroom under Discord's ~5-per-20s ceiling.
+  maxActivityWrites: 4,
+  activityWindowMs: 20000,
   rescanIntervalSec: 300,
   idleThresholdSec: 60,
   // Time (minutes) of no hook activity AND no live transcripts on disk before

package/src/gist.js

@@ -27,9 +27,11 @@ function ghQuote(a) {
   return /[\s"]/.test(a) ? `"${String(a).replace(/"/g, '""')}"` : a;
 }
 function gh(args, opts = {}) {
+  // windowsHide so the gh.exe/cmd shim doesn't flash a console window on
+  // Windows (shell:true routes through cmd.exe; hide that too). No-op elsewhere.
   return WIN
-    ? spawnSync('gh', args.map(ghQuote), { ...opts, shell: true })
-    : spawnSync('gh', args, opts);
+    ? spawnSync('gh', args.map(ghQuote), { ...opts, shell: true, windowsHide: true })
+    : spawnSync('gh', args, { ...opts, windowsHide: true });
 }
 
 // Bare fetch has no total timeout; a stalled GitHub endpoint would hang the

package/src/install.js

@@ -447,15 +447,15 @@ export function installMcp({ exePath, scope = 'user' } = {}) {
   const { command, args } = mcpServerCommand(exePath);
   const winShell = process.platform === 'win32';
   // Replace any stale entry first so re-running is idempotent (ignore failure).
-  spawnSync('claude', ['mcp', 'remove', 'claude-rpc', '--scope', scope], { stdio: 'ignore', shell: winShell });
-  const r = spawnSync('claude', ['mcp', 'add', 'claude-rpc', '--scope', scope, '--', command, ...args], { stdio: 'inherit', shell: winShell });
+  spawnSync('claude', ['mcp', 'remove', 'claude-rpc', '--scope', scope], { stdio: 'ignore', shell: winShell, windowsHide: true });
+  const r = spawnSync('claude', ['mcp', 'add', 'claude-rpc', '--scope', scope, '--', command, ...args], { stdio: 'inherit', shell: winShell, windowsHide: true });
   if (r.error && r.error.code === 'ENOENT') return { ok: false, reason: 'no-claude', command, args };
   if (r.status !== 0) return { ok: false, reason: 'add-failed', code: r.status, command, args };
   return { ok: true, command, args, scope };
 }
 
 export function uninstallMcp({ scope = 'user' } = {}) {
-  const r = spawnSync('claude', ['mcp', 'remove', 'claude-rpc', '--scope', scope], { stdio: 'inherit', shell: process.platform === 'win32' });
+  const r = spawnSync('claude', ['mcp', 'remove', 'claude-rpc', '--scope', scope], { stdio: 'inherit', shell: process.platform === 'win32', windowsHide: true });
   if (r.error && r.error.code === 'ENOENT') return { ok: false, reason: 'no-claude' };
   return { ok: r.status === 0 };
 }
@@ -666,6 +666,7 @@ function promoteNpxToGlobal() {
   const r = spawnSync('npm', ['install', '-g', `claude-rpc@${VERSION}`], {
     encoding: 'utf8',
     shell: process.platform === 'win32',   // npm is npm.cmd on Windows
+    windowsHide: true,                      // don't flash a console window
   });
   if (r.error || r.status !== 0) {
     // The piped npm chatter only matters when it failed.
@@ -687,6 +688,7 @@ function warnIfStale() {
     const r = spawnSync('npm', ['view', 'claude-rpc', 'version'], {
       encoding: 'utf8', timeout: 4000,
       shell: process.platform === 'win32',   // npm is npm.cmd on Windows
+      windowsHide: true,                      // don't flash a console window
     });
     const latest = (r.stdout || '').trim();
     if (!latest || latest === VERSION) return;

package/src/presence.js

@@ -113,9 +113,35 @@ export function shouldShowGithubButton(p, state) {
 //   - 'defer' : inside the gap, or a flush is already queued — coalesce to the
 //               LATEST payload and let the caller flush it in `waitMs`, so the
 //               final state of every burst still lands, once, under the limit
-export function throttleDecision({ hash, lastSentHash, lastSentAt, now, gapMs, flushPending }) {
+//
+// The per-write `gapMs` only spaces *consecutive* writes; it does NOT bound
+// writes-per-window. With gapMs == windowMs/maxPerWindow (the 4s default sits
+// exactly on Discord's ~5-per-20s ceiling) a 20s window can still catch
+// floor(windowMs/gapMs)+1 == 6 gap-spaced writes — one over the limit — because
+// many independent triggers (the rotation tick re-rendering {toolElapsed}, a
+// background scan, a live-session change, a config reload) each want to write.
+// That extra write is exactly what makes Discord EMPTY the presence (the card
+// collapses to just the app name + elapsed timer). So when `recentSends` (the
+// timestamps of recent writes, set+clear) and `maxPerWindow` are supplied we
+// add a hard sliding-window cap on top of the gap: defer until the oldest write
+// in the window expires, guaranteeing no more than `maxPerWindow` writes in any
+// `windowMs` no matter how many triggers fire. Omitting them keeps the old
+// gap-only behavior (used by tests that predate the cap).
+export function throttleDecision({ hash, lastSentHash, lastSentAt, now, gapMs, flushPending, recentSends, windowMs, maxPerWindow }) {
   if (hash === lastSentHash) return { action: 'skip', waitMs: 0 };
-  const waitMs = Math.max(0, (lastSentAt || 0) + gapMs - now);
+  let waitMs = Math.max(0, (lastSentAt || 0) + gapMs - now);
+  if (maxPerWindow && windowMs && Array.isArray(recentSends)) {
+    // Strict window (age < windowMs) so a write exactly windowMs old has already
+    // fallen out — matches a "requests in the last 20s" limiter and keeps the
+    // boundary case from sneaking a write over the line.
+    const inWindow = recentSends.filter((t) => t > now - windowMs);
+    if (inWindow.length >= maxPerWindow) {
+      // The oldest write we must let expire before another may go out. Once it
+      // ages past windowMs the window drops below the cap and we can send.
+      const oldest = inWindow[inWindow.length - maxPerWindow];
+      waitMs = Math.max(waitMs, oldest + windowMs - now);
+    }
+  }
   if (waitMs === 0 && !flushPending) return { action: 'send', waitMs: 0 };
   return { action: 'defer', waitMs };
 }

package/src/privacy.js

@@ -197,7 +197,12 @@ function probeGithubPrivate(cwd) {
   execFile(
     'gh',
     ['repo', 'view', '--json', 'isPrivate', '-q', '.isPrivate'],
-    { cwd, timeout: 1500 },
+    // windowsHide: on Windows `gh` is a console app; without this the daemon —
+    // which runs with no console of its own — pops a visible terminal window for
+    // the life of the probe (~1s) every time this fires (a cwd cache-miss, i.e.
+    // entering a project, then once per 5-min TTL). That's the stray terminal
+    // flash users see "sometimes" while working. No-op off Windows.
+    { cwd, timeout: 1500, windowsHide: true },
     (err, stdout) => {
       ghProbeInFlight.delete(cwd);
       let value = null;

package/src/server/index.js

@@ -133,7 +133,8 @@ server.listen(PORT, '127.0.0.1', () => {
     const opener = process.platform === 'win32' ? `start "" "${url}"`
       : process.platform === 'darwin' ? `open "${url}"`
       : `xdg-open "${url}"`;
-    exec(opener, () => {});
+    // windowsHide so the cmd.exe that runs `start` doesn't flash a console.
+    exec(opener, { windowsHide: true }, () => {});
   }
 });
 

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.24.1';
+const BAKED = '1.0.2';
 
 function readPkgVersion() {
   try {