claude-rpc 0.7.3 → 0.8.0

package/README.md

@@ -43,6 +43,8 @@ claude-rpc start
 
 That's the whole pitch. Open Claude Code in any project — the daemon picks it up within a second. Something looks wrong? `claude-rpc doctor`.
 
+> `setup` registers a Windows startup entry and wires hooks into Claude Code's `settings.json`, and the daemon reports anonymous totals by default. All of it is reversible (`claude-rpc uninstall`, `community off`) and fully documented in [`SECURITY.md`](SECURITY.md) — read it first if you want to know exactly what runs.
+
 The Discord *desktop* app must be running. The browser client doesn't expose the local IPC bridge that Rich Presence uses.
 
 <details>
@@ -142,6 +144,8 @@ 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.
 
+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.
+
 ## three pieces, glued by json files
 
 ```

package/SECURITY.md

@@ -0,0 +1,169 @@
+# Security & behavior disclosure
+
+claude-rpc is a Discord Rich Presence daemon for Claude Code. To do its job it
+has to (a) register itself to start on login and (b) wire commands into Claude
+Code's hook system. Both are legitimate, documented behaviors — but they are
+also patterns that automated supply-chain scanners (e.g. Socket.dev) flag,
+because malware persists and injects the same way. This document is the
+audit trail: every sensitive thing the package does, where in the source it
+lives, why it's there, its blast radius, and how to reverse or disable it.
+
+Everything below is verifiable against the published source — there is no
+minified bundle, no obfuscation, no `eval`/`new Function`, and no remote code
+fetch-and-execute anywhere in `src/`.
+
+## TL;DR for reviewers
+
+| Behavior | Where | Scope | Reversible? |
+| --- | --- | --- | --- |
+| Startup persistence | `src/install.js` → `addStartupEntry` | `HKCU` Run key, current user, no admin | Yes — `claude-rpc uninstall` / `removeStartupEntry` |
+| Hook injection | `src/install.js` → `installHooks` | Only into Claude Code's own `settings.json`, only our own commands | Yes — `uninstallHooks` removes exactly what it added |
+| Outbound network | `src/community.js`, `src/gist.js`, `default-config.js` asset URLs | Anonymous counters + (opt-in) gist publish + GIF assets | Telemetry: `community off`. Gist: only on explicit `badge --gist`. |
+| Local subprocess | `reg.exe`, `git`, `gh` | Static args, no shell interpolation of untrusted input | n/a |
+
+No credential access, no filesystem scanning outside `~/.claude-rpc` and Claude
+Code transcripts, no keylogging, no clipboard access, no AV/EDR evasion.
+
+## 1. Startup persistence (Windows Run key)
+
+**Source:** `src/install.js`, `addStartupEntry` / `removeStartupEntry`.
+
+On Windows, `setup` writes one value:
+
+```
+HKCU\Software\Microsoft\Windows\CurrentVersion\Run
+  ClaudeRPC = "<path-to-exe>" daemon
+```
+
+- **Why:** the Discord presence is driven by a long-lived daemon. If it doesn't
+  restart on login, your presence silently stops working after every reboot.
+- **Scope:** `HKCU` (current user) only. No admin elevation, no `HKLM`, no
+  service install, no scheduled task.
+- **Reverse it:** `claude-rpc uninstall` deletes the value. You can also delete
+  it by hand in `regedit` or with
+  `reg delete "HKCU\...\Run" /v ClaudeRPC /f`.
+- The value points at the canonical install path (`%LOCALAPPDATA%`-class dir),
+  not at wherever you happened to run the installer from — see
+  `ensureCanonicalExe`.
+
+Non-Windows platforms get **no** persistence registration (`install()` warns
+and skips it).
+
+## 2. Hook injection into Claude Code
+
+**Source:** `src/install.js`, `installHooks` / `uninstallHooks`.
+
+`setup` adds command hooks to Claude Code's `settings.json` for eight lifecycle
+events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`,
+`Stop`, `SubagentStop`, `Notification`, `SessionEnd`. Each entry looks like:
+
+```jsonc
+{ "matcher": "", "hooks": [{ "type": "command", "command": "\"<exe>\" hook PostToolUse" }] }
+```
+
+- **Why:** this *is* the integration. Claude Code's hook system is the
+  supported, documented way for a tool to observe session lifecycle. The hook
+  reads the event JSON on stdin, updates `~/.claude-rpc/state.json`, and prints
+  `{"continue":true}`. It never blocks, rewrites, or vetoes a tool call — see
+  `src/hook.js`, `processHookEvent`.
+- **What the hook reads:** tool name, file path of the active tool, token usage
+  counters, and `git push`/`git commit` detection (for the "just shipped"
+  card). It writes only to local state/log files. It does not read file
+  *contents*, prompts, or responses beyond the usage counters Claude provides.
+- **Scope:** the installer only ever touches entries whose command matches
+  `isOurHookCommand` (contains `claude-rpc` or `hook.js`). It will not modify,
+  reorder, or delete anyone else's hooks.
+- **Reverse it:** `claude-rpc uninstall` (or `uninstallHooks`) strips exactly
+  the entries it added and leaves the rest of `settings.json` intact.
+
+## 3. Outbound network
+
+There are three distinct network behaviors. Two are optional; one is cosmetic.
+
+### 3a. Community totals (telemetry) — ON by default for fresh installs
+
+**Source:** `src/community.js`; endpoint in `src/default-config.js`
+(`community.endpoint`); receiving end is the full Worker source in
+[`worker/src/index.js`](worker/src/index.js).
+
+A fresh install mints an anonymous UUID v4 and the daemon POSTs to
+`https://claude-rpc-totals.claude-rpc.workers.dev/report` every 30 minutes.
+The **complete** payload (see `buildPayload`, enforced by the Worker's
+`validateReport`) is:
+
+```json
+{
+  "instanceId": "<random UUID v4>",
+  "sessionsDelta": 3,
+  "tokensDelta": 142000,
+  "version": "0.7.3",
+  "osFamily": "win32",
+  "ts": 1716500000000
+}
+```
+
+What is **not** sent, ever: prompts, responses, file paths, file contents,
+project/repo names, models, cost figures, usernames, hostnames, IP (beyond what
+any HTTP request inherently exposes to Cloudflare's edge), or absolute counter
+values — only forward deltas since the last accepted report.
+
+- **Opt out any time:** `claude-rpc community off`.
+- **Upgraders are protected:** anyone upgrading from a pre-v0.7 config is
+  written `community.enabled: false`; re-enabling requires the explicit consent
+  flow `claude-rpc community on`, which prints the payload schema first.
+- **Why on by default:** the live badges in the README aggregate these counters.
+  The trade-off is disclosed here, in the README, and at install time.
+- **Auditable:** the Worker persists only two running integers and a 30-day
+  `seen:<instanceId>` dedup marker. The source is in this repo.
+
+### 3b. Gist badge publishing — only on explicit command
+
+**Source:** `src/gist.js`. Runs **only** when you run `claude-rpc badge --gist`.
+Publishes a badge SVG to *your own* GitHub gist via the `gh` CLI or a
+`GH_TOKEN` you supply with `gist` scope. Hits `api.github.com` /
+`gist.github.com`. Never runs unattended, never on install, never from the
+daemon.
+
+### 3c. Presence GIF assets — Discord-side only
+
+`default-config.js` references `https://cdn.qualit.ly/clawd-*.gif`. These URLs
+are handed to Discord as image keys; **Discord's** client fetches them to render
+the card. The daemon itself doesn't download them. Swap them for your own URLs
+in `config.json` if you prefer.
+
+## 4. Local subprocesses
+
+All `child_process` use is static-argument and visible:
+
+- `reg.exe add/delete` — the Run key above (`src/install.js`).
+- `git` — read last commit subject / branch for the "just shipped" card
+  (`src/git.js`).
+- `gh repo view --json isPrivate` — auto-hide GitHub-private repos from the card
+  (`src/privacy.js`); 1.5s timeout, silent skip if `gh` is absent.
+- `gh gist` — only under 3b above.
+
+No subprocess interpolates untrusted/remote input into a shell. The one
+`shell: true` call (`verifyHookPipe`) uses only static, trusted args and is
+documented inline as such.
+
+## 5. What it stores locally
+
+Under `~/.claude-rpc/` (a.k.a. `%APPDATA%\claude-rpc\` on Windows):
+`config.json`, `state.json`, `aggregate.json`, `events.jsonl` (rotated at 5 MB),
+`private-list.json`, `community-cursor.json`. The scanner also reads Claude Code
+transcript files to build aggregates. None of this leaves your machine except
+the minimal telemetry in 3a.
+
+## 6. Privacy controls
+
+Independent of telemetry, the Discord card has a privacy valve (`src/privacy.js`):
+per-project `.claude-rpc.json`, a runtime private-list, config glob patterns, and
+`gh`-based auto-hide of private repos. Levels: `public` / `name-only` / `hidden`.
+Local dashboards and aggregates are never redacted — privacy is a one-way valve
+from local state to Discord only.
+
+## Reporting a vulnerability
+
+Open an issue at https://github.com/rar-file/claude-rpc/issues, or for anything
+sensitive email c.archer.simmons@gmail.com. Please include version
+(`claude-rpc --version`), OS, and repro steps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-rpc",
-  "version": "0.7.3",
+  "version": "0.8.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",
@@ -57,6 +57,7 @@
     "src",
     "config.example.json",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "SECURITY.md"
   ]
 }

package/src/daemon.js

@@ -282,9 +282,33 @@ async function pushPresence() {
     log('Presence updated:', activity.details || '-', '|', activity.state || '-');
   } catch (e) {
     log('setActivity failed:', e.message, '|', e.stack?.split('\n').slice(0, 3).join(' | '));
+    // A failed setActivity usually means the IPC pipe died WITHOUT the client
+    // emitting a 'disconnected' event (Discord restart, socket reset, OS
+    // sleep). Left alone, `connected` stays true and the daemon goes silently
+    // dark forever. Tear the client down and force a backoff reconnect so we
+    // self-heal. Guarded to connection-shaped errors so a one-off API hiccup
+    // doesn't needlessly bounce a healthy socket.
+    if (isConnectionError(e)) {
+      log('setActivity error looks connection-level — forcing reconnect');
+      connected = false;
+      lastPayloadHash = '';
+      try { client?.destroy(); } catch { /* already gone */ }
+      scheduleReconnect('setActivity failed');
+    }
   }
 }
 
+// Heuristic: does this error indicate the IPC transport itself is dead
+// (vs. a transient/application-level failure)? Matches the common broken-pipe
+// / closed-socket shapes from @xhayper/discord-rpc and the underlying net
+// socket so we only force a reconnect when the connection is actually gone.
+function isConnectionError(e) {
+  const code = (e && e.code) || '';
+  if (['EPIPE', 'ECONNRESET', 'ENOENT', 'ECONNREFUSED', 'ERR_STREAM_WRITE_AFTER_END'].includes(code)) return true;
+  const m = String((e && e.message) || '').toLowerCase();
+  return /closed|reset|broken pipe|not connected|disconnect|write after end|socket|econnreset|epipe|connection/.test(m);
+}
+
 async function connect() {
   if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
   client = new Client({ clientId: config.clientId, transport: { type: 'ipc' } });
@@ -454,6 +478,36 @@ function refreshLiveSessions() {
 refreshLiveSessions();
 setInterval(refreshLiveSessions, 30_000);
 
+// ── Connection watchdog (auto-heal) ──────────────────────────────────────────
+// The reconnect path is event-driven (the 'disconnected' handler + login
+// failures + setActivity errors). But a connection can rot in ways that emit
+// no event at all: a half-open client where `connected` is still true but the
+// user handle is gone, or a state where we're down with no retry in flight.
+// This periodic check guarantees the daemon always converges back to a live
+// connection instead of silently staying dark — the single most common
+// "it just stopped showing up" failure users hit.
+const HEALTH_CHECK_MS = 30_000;
+setInterval(() => {
+  try {
+    // Half-open: flag says connected but there's no usable user handle.
+    if (connected && !client?.user) {
+      log('Watchdog: connected but no user handle — forcing reconnect');
+      connected = false;
+      try { client?.destroy(); } catch { /* already gone */ }
+      scheduleReconnect('watchdog: half-open');
+      return;
+    }
+    // Down with nothing scheduled to bring us back. scheduleReconnect is a
+    // no-op when a timer is already pending, so this can't stack retries.
+    if (!connected && !reconnectTimer) {
+      log('Watchdog: disconnected with no reconnect pending — forcing reconnect');
+      scheduleReconnect('watchdog: no retry pending');
+    }
+  } catch (e) {
+    log('Watchdog tick failed:', e.message);
+  }
+}, HEALTH_CHECK_MS);
+
 // Community-totals flush. Disabled by default; turns on via
 // `claude-rpc community on`. Best-effort — flushCommunity swallows every
 // failure mode, so a flaky endpoint or no network just means the deltas

package/src/default-config.js

@@ -21,6 +21,12 @@ export const DEFAULT_CONFIG = {
   // when Claude isn't open, the Discord presence should disappear quickly.
   // The SessionEnd hook short-circuits this — see hook.js + format.applyIdle.
   staleSessionMin: 5,
+  // When the Claude Code session is still open but its transcript has gone
+  // quiet (you paused, stepped away briefly), show 'idle' rather than
+  // clearing the card. Only an authoritative SessionEnd or the full
+  // staleSessionMin dormancy window drops to stale. Set false to restore the
+  // old behavior (clear ~90-120s after the last transcript write).
+  idleWhenOpen: true,
   // When true, the daemon CLEARS Discord activity entirely once the state
   // goes stale — your profile shows nothing instead of an "Away" frame.
   hideWhenStale: true,
@@ -119,7 +125,7 @@ export const DEFAULT_CONFIG = {
     },
 
     buttons: [
-      { label: "Claude Code", url: "https://claude.com/claude-code" },
+      { label: "Claude Code", url: "https://github.com/rar-file/claude-rpc" },
     ],
   },
   statusIcons: {

package/src/doctor.js

@@ -228,19 +228,30 @@ function checkDaemonLog() {
   }
   const ageMin = (Date.now() - st.mtimeMs) / 60_000;
   const sizeKB = (st.size / 1024).toFixed(1);
-  // Look for "Discord RPC connected" in the tail to confirm Discord IPC.
-  let connected = false;
+  // Infer live IPC state from the log. The daemon connects once and stays
+  // connected without re-logging, so grepping only for "connected" produces
+  // a false warning on a long-lived daemon. Instead: "Discord RPC connected",
+  // "Presence updated", and "Presence cleared" all imply a live connection —
+  // the latter two only log *after* the daemon's `connected` guard passes and
+  // a setActivity/clearActivity succeeds (see daemon.js). A later "retry in
+  // Ns" / "login failed" / "disconnected" line means it dropped. Whichever
+  // happened most recently wins.
+  let ipc = 'unknown';
   try {
-    const tail = readFileSync(LOG_PATH, 'utf8').split('\n').slice(-50).join('\n');
-    connected = /Discord RPC connected/i.test(tail);
-  } catch { /* log unreadable — connected stays false, warn check renders */ }
-  if (connected) {
+    for (const line of readFileSync(LOG_PATH, 'utf8').split('\n').slice(-80)) {
+      if (/Discord RPC connected|Presence updated|Presence cleared/i.test(line)) ipc = 'up';
+      else if (/retry in \d+s|login failed|Discord disconnected/i.test(line)) ipc = 'down';
+    }
+  } catch { /* log unreadable — ipc stays 'unknown', warn renders */ }
+  if (ipc === 'up') {
     check('discord IPC connection', 'pass',
-      `${sizeKB} KB log · last write ${ageMin.toFixed(1)} min ago`);
-  } else {
-    check('discord IPC connection', 'warn',
-      `log shows no recent "connected" line`,
+      `connected · ${sizeKB} KB log · last write ${ageMin.toFixed(1)} min ago`);
+  } else if (ipc === 'down') {
+    check('discord IPC connection', 'warn', 'daemon is reconnecting to Discord',
       'is the discord desktop client running? rpc only works via desktop, not browser');
+  } else {
+    check('discord IPC connection', 'warn', 'no connection activity in the log yet',
+      'start the daemon with discord desktop running');
   }
 }
 

package/src/format.js

@@ -682,6 +682,12 @@ export function applyIdle(state, cfg = {}) {
   const idleMs = (cfg.idleThresholdSec || 60) * 1000;
   const staleMs = Math.max(60_000, (cfg.staleSessionMin || 5) * 60 * 1000);
   const notificationMs = (cfg.notificationWindowSec || 8) * 1000;
+  // When the Claude Code session is still open (no authoritative SessionEnd)
+  // but its transcript has gone quiet, prefer 'idle' over clearing the card.
+  // Only an explicit close (claudeClosed) or the staleMs dormancy backstop
+  // drops us to stale. Default on; set idleWhenOpen:false to restore the old
+  // aggressive ~90-120s clear when no transcript is being written.
+  const idleWhenOpen = cfg.idleWhenOpen !== false;
 
   // Authoritative close signal from the SessionEnd hook — trust it instead
   // of waiting on staleSessionMin. Any other hook clears the flag, so a
@@ -730,24 +736,26 @@ export function applyIdle(state, cfg = {}) {
 
   // Local state is fresh.
   if (state.status === 'idle') {
-    // Fast-path stale: if there are NO transcripts being written anywhere
-    // on disk, Claude Code isn't running. SessionEnd may not have fired
-    // (force-quit, OS sleep, crash). Going stale here clears Discord
-    // within ~90-120s of close instead of waiting the full staleMs (5min)
-    // — keeps the user's cwd off the card when they're away from their
-    // machine. The 5min legacy fallback below still catches the case
-    // where transcript mtime is fresh but the hook channel is silent.
-    if (liveSessions.length === 0) return staleWipe(state);
+    // No transcripts being written anywhere on disk — Claude Code may have
+    // closed without a SessionEnd hook (force-quit, OS sleep, crash). With
+    // idleWhenOpen (default) we keep showing 'idle': the session hasn't been
+    // authoritatively closed and the staleMs dormancy backstop above will
+    // still clear it if Claude is truly gone. Set idleWhenOpen:false to go
+    // straight to stale here — clears Discord ~90-120s after the last write,
+    // at the cost of dropping the card whenever you pause for a couple
+    // minutes with the session still open.
+    if (liveSessions.length === 0 && !idleWhenOpen) return staleWipe(state);
     return state;
   }
   if (ageMs > idleMs) {
     // Hook channel is quiet, but a live transcript was modified recently?
     // Keep "working" instead of dropping to "idle".
     if (liveAgeMs <= idleMs) return state;
-    // Hooks quiet AND no live transcripts → Claude is closed, not paused.
-    // Skip idle, go straight to stale. Same privacy reasoning as the
-    // idle-state fast-path above.
-    if (liveSessions.length === 0) return staleWipe(state);
+    // Hooks quiet AND no live transcripts. With idleWhenOpen (default) the
+    // session is treated as open-but-paused and drops to idle; the staleMs
+    // backstop above clears it if Claude is actually gone. Set
+    // idleWhenOpen:false to go straight to stale here (old behavior).
+    if (liveSessions.length === 0 && !idleWhenOpen) return staleWipe(state);
     // Going idle — wipe "current activity" indicators so rotation frames
     // gated on filesEdited / currentFile / currentTool stop showing stale
     // active-session data. Keep the session counters (messages/tools/tokens)

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