claude-rpc 0.20.4 → 0.21.0

package/SECURITY.md

@@ -16,7 +16,7 @@ fetch-and-execute anywhere in `src/`.
 
 | Behavior | Where | Scope | Reversible? |
 | --- | --- | --- | --- |
-| Startup persistence | `src/install.js` → `addStartupEntry` (Windows Run key); `src/hook.js` → `ensureDaemonRunning` (SessionStart self-heal, all platforms) | `HKCU` Run key (no admin) + a detached daemon (re)launched when you start a Claude Code session | Yes — `claude-rpc uninstall` / `removeStartupEntry`; disable self-heal with `autostart:false` |
+| Startup persistence | `src/install.js` → `addStartupEntry` (Windows Run key, macOS LaunchAgent, Linux `systemd --user`) + `selfHealOnUpdate` (installs it on update); `src/hook.js` → `ensureDaemonRunning` (SessionStart self-heal) | Per-user login autostart (no admin/root/system service) + a detached daemon (re)launched when you start a Claude Code session | Yes — `claude-rpc uninstall` / `removeStartupEntry`; disable every auto-start path with `autostart:false` |
 | 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`, `src/usage.js`, `src/notify.js`, `default-config.js` | Anonymous counters + (opt-in) profile/gist/webhook + own read-only OAuth-usage poll + GIF assets | Telemetry: `community off`. Profile: `profile off`. Gist/webhook: opt-in only. Usage: `usage.enabled:false`. |
 | Local subprocess | `reg.exe`, `wscript`, the daemon itself (`node`/packaged exe — via the Run key and the SessionStart self-heal), `git`, `gh`, `npm`, `claude`, `security`, notifiers | Static or escaped args, no shell interpolation of untrusted input | n/a |
@@ -25,9 +25,10 @@ No credential access beyond the read-only Claude Code OAuth-token read for usage
 polling (§3d), 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)
+## 1. Startup persistence (login autostart, all platforms)
 
-**Source:** `src/install.js`, `addStartupEntry` / `removeStartupEntry`.
+**Source:** `src/install.js`, `addStartupEntry` / `removeStartupEntry`; the
+on-update install path lives in `selfHealOnUpdate`.
 
 On Windows, `setup` writes one value:
 
@@ -47,16 +48,38 @@ HKCU\Software\Microsoft\Windows\CurrentVersion\Run
   not at wherever you happened to run the installer from — see
   `ensureCanonicalExe`.
 
-Non-Windows platforms get **no** Run-key/login registration (`install()` warns
-and skips it). Instead — on every platform, Windows included — the
-`SessionStart` hook **self-heals** the daemon: if none is running when you start
-a Claude Code session, the hook spawns one (detached, windowless), so presence
-is restored after a reboot, crash, or OS sleep exactly when you next use Claude.
-It is the same long-lived daemon launched the same way (`src/ensure-daemon.js` →
+**macOS and Linux** now get login autostart too, at per-user parity with Windows:
+
+```
+macOS  ~/Library/LaunchAgents/com.claude-rpc.daemon.plist   (launchctl, RunAtLoad)
+Linux  ~/.config/systemd/user/claude-rpc.service            (systemctl --user enable)
+```
+
+- **Scope:** per-user only — a user LaunchAgent / `systemctl --user` unit, never
+  a root/system daemon, LaunchDaemon, or system-wide service. No admin, no `sudo`.
+- **Reverse it:** `claude-rpc uninstall` removes the plist/unit and unloads it
+  (`removeStartupEntry`); or delete the file and `launchctl unload` /
+  `systemctl --user disable` by hand.
+
+**A login-autostart entry can appear on UPDATE, not only at `setup`.** Because
+npm runs no install script (see intro), an `npm update` reaches you through the
+daemon: the first time it starts after an update, `selfHealOnUpdate` re-wires
+hooks, migrates config, **and installs the login-autostart entry above** so the
+daemon comes up at login on the new version. This is the one place a
+background-start entry is created without an explicit `setup`. It is gated by
+`autostart` (default on) — set `autostart:false` to opt out of every auto-start
+path — and is best-effort: if `launchctl`/`systemctl`/`reg` fails, nothing
+breaks (the session self-heal below still covers startup).
+
+Underneath all of this, on every platform, the `SessionStart` hook also
+**self-heals** the daemon: if none is running when you start a Claude Code
+session, the hook spawns one (detached, windowless), so presence is restored
+after a reboot, crash, or OS sleep exactly when you next use Claude. It is the
+same long-lived daemon launched the same way (`src/ensure-daemon.js` →
 `spawnDaemonDetached`), a no-op when a daemon is already running, and
 cooldown-guarded against spawn storms; the daemon's atomic single-instance claim
-reaps any duplicate. Disable it with `autostart:false` in config (then manage
-the daemon yourself via `claude-rpc start` / `stop`).
+reaps any duplicate. Disable everything with `autostart:false` in config (then
+manage the daemon yourself via `claude-rpc start` / `stop`).
 
 ## 2. Hook injection into Claude Code
 
@@ -256,6 +279,10 @@ untrusted or remote input into a shell:
 
 - `reg.exe add/delete` — the Windows Run key (`src/install.js`).
 - `wscript.exe` — runs the generated windowless startup shim (`src/install.js`).
+- `launchctl load/unload` — the macOS LaunchAgent (`src/install.js`); args are
+  the fixed plist path.
+- `systemctl --user enable/disable/daemon-reload` — the Linux user service
+  (`src/install.js`); args are the fixed unit name.
 - `chcp.com 65001` — set the console to UTF-8 on Windows TTYs (`src/cli.js`).
 - `git` — read last commit subject / branch for the "just shipped" card
   (`src/git.js`).

package/package.json

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

@@ -10,7 +10,8 @@ import { detectGithubUrl } from './git.js';
 import { applyPrivacy } from './privacy.js';
 import { pauseUntil } from './pause.js';
 import { loadConfig } from './config.js';
-import { migrateConfig } from './install.js';
+import { selfHealOnUpdate } from './install.js';
+import { VERSION } from './version.js';
 import { desktopNotify, postWebhook, shouldWebhook, shouldNotify, sanitizeLabel } from './notify.js';
 import { humanProject } from './format.js';
 import { CONFIG_PATH, STATE_PATH, PID_PATH, LOG_PATH, STATE_DIR, AGGREGATE_PATH, PAUSE_PATH } from './paths.js';
@@ -79,12 +80,20 @@ function loadConfigWithLog() {
 // move. Idempotent: only writes when something actually changes, so steady-state
 // restarts are a no-op and can't loop the config watcher. Best-effort — a
 // migration failure must never stop the daemon from starting.
+// Self-heal on update — when this daemon is a newer version than the last one
+// that ran, re-wire hooks (their command/path drifts across versions) and
+// migrate config to the current shape, then stamp the version. This is how an
+// `npm update` reaches users who never re-run setup: there is no install script
+// (by design), so the daemon — itself brought up by the SessionStart self-heal —
+// carries the update forward. A since-0.1.0 install converges to the current
+// hooks + config the first time it's used after updating.
 try {
-  if (migrateConfig({ silent: true })) {
-    log('config.json migrated to current defaults on startup');
+  const healed = selfHealOnUpdate({ silent: true });
+  if (healed.changed) {
+    log(`self-heal on update: ${healed.from || 'fresh'} → ${VERSION} (hooks ${healed.rewired ? 're-wired' : 'already current'}, config migrated${healed.autostart ? ', login autostart ensured' : ''})`);
   }
 } catch (e) {
-  log('startup config migration failed (continuing):', e?.message || String(e));
+  log('startup self-heal failed (continuing):', e?.message || String(e));
 }
 
 let config = loadConfigWithLog();

package/src/install.js

@@ -8,12 +8,14 @@ import {
   readdirSync, unlinkSync,
 } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
 import { spawn, spawnSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import {
   CLAUDE_SETTINGS, CONFIG_PATH, USER_CONFIG_DIR, ROOT,
   HOOK_SCRIPT, IS_PACKAGED, IS_NPM_INSTALL, IS_NPX,
-  CANONICAL_EXE, CANONICAL_INSTALL_DIR, CANONICAL_EXE_NAME,
+  CANONICAL_EXE, CANONICAL_INSTALL_DIR, CANONICAL_EXE_NAME, VERSION_STAMP,
+  DAEMON_SCRIPT,
 } from './paths.js';
 import { DEFAULT_CONFIG } from './default-config.js';
 import { VERSION } from './version.js';
@@ -83,7 +85,7 @@ export function isOurHook(h) {
   return !!h && (h._claudeRpc === true || isOurHookCommand(h.command));
 }
 
-export function installHooks(exePath) {
+export function installHooks(exePath, { silent = false } = {}) {
   const settings = readJson(CLAUDE_SETTINGS, {});
   const before = JSON.stringify(settings.hooks || {});
   settings.hooks = settings.hooks || {};
@@ -118,11 +120,11 @@ export function installHooks(exePath) {
     }
   }
   if (JSON.stringify(settings.hooks) === before) {
-    noop(`hooks wired (${EVENTS.length} events)`);
+    if (!silent) noop(`hooks wired (${EVENTS.length} events)`);
     return false;
   }
   writeJson(CLAUDE_SETTINGS, settings);
-  dirtyStep(SYM_OK, 'hooks wired', `${EVENTS.length} events → ${CLAUDE_SETTINGS}`);
+  if (!silent) dirtyStep(SYM_OK, 'hooks wired', `${EVENTS.length} events → ${CLAUDE_SETTINGS}`);
   return true;
 }
 
@@ -153,7 +155,129 @@ function regCommand(args) {
 
 const STARTUP_VBS = join(CANONICAL_INSTALL_DIR, 'claude-rpc-daemon.vbs');
 
+// macOS LaunchAgent + Linux systemd --user paths/labels.
+const LAUNCHD_LABEL = 'com.claude-rpc.daemon';
+const LAUNCHD_PLIST = join(homedir(), 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
+const SYSTEMD_UNIT_NAME = 'claude-rpc.service';
+const SYSTEMD_UNIT = join(homedir(), '.config', 'systemd', 'user', SYSTEMD_UNIT_NAME);
+
+// The daemon launch command, shared by every autostart mechanism so login/boot
+// starts the daemon exactly like `start` and the hook do:
+//   packaged → "<exe>" daemon ;  npm/dev → "<abs node>" "<abs daemon.js>"
+// (absolute node, like the hooks — login shells under nvm have no node on PATH).
+function daemonLaunch(exePath) {
+  if (IS_PACKAGED) return { exe: exePath, args: ['daemon'] };
+  return { exe: process.execPath, args: [DAEMON_SCRIPT] };
+}
+
+function xmlEscape(s) { return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'); }
+function systemctlUser(args) {
+  try { return spawnSync('systemctl', ['--user', ...args], { stdio: 'ignore' }); }
+  catch { return { status: 1 }; }
+}
+
+// Pure file-content builders — exported so the generated plist/unit are
+// unit-testable without touching launchctl/systemctl or the real filesystem.
+export function launchdPlist({ exe, args }) {
+  const progArgs = [exe, ...args].map((a) => `    <string>${xmlEscape(a)}</string>`).join('\n');
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    '<dict>',
+    `  <key>Label</key><string>${LAUNCHD_LABEL}</string>`,
+    '  <key>ProgramArguments</key>',
+    '  <array>',
+    progArgs,
+    '  </array>',
+    '  <key>RunAtLoad</key><true/>',
+    // KeepAlive false: start at login, but don't fight a manual `claude-rpc stop`.
+    '  <key>KeepAlive</key><false/>',
+    '  <key>ProcessType</key><string>Background</string>',
+    '</dict>',
+    '</plist>',
+    '',
+  ].join('\n');
+}
+
+export function systemdUnit({ exe, args }) {
+  const execStart = [exe, ...args].map((a) => `"${a}"`).join(' '); // quote each token (paths with spaces)
+  return [
+    '[Unit]',
+    'Description=claude-rpc — Discord Rich Presence for Claude Code',
+    'After=default.target',
+    '',
+    '[Service]',
+    'Type=simple',
+    `ExecStart=${execStart}`,
+    // on-failure (not always): a clean exit when another daemon already owns the
+    // instance must NOT be restarted, and neither should a `claude-rpc stop`.
+    'Restart=on-failure',
+    'RestartSec=5',
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+    '',
+  ].join('\n');
+}
+
+// ── macOS: launchd LaunchAgent (per-user, starts at login) ────────────────────
+function addStartupEntryMac(exePath) {
+  const plist = launchdPlist(daemonLaunch(exePath));
+  try {
+    mkdirSync(dirname(LAUNCHD_PLIST), { recursive: true });
+    writeFileSync(LAUNCHD_PLIST, plist);
+  } catch (e) {
+    step(SYM_WARN, 'startup entry', `couldn't write LaunchAgent (${e.message}) — the session self-heal still starts the daemon`, console.warn);
+    return;
+  }
+  // Load so it's active now and at every login. `load -w` is deprecated but
+  // portable across the macOS versions we target; a failure is non-fatal — the
+  // plist alone starts it next login, and SessionStart self-heal covers the gap.
+  try { spawnSync('launchctl', ['unload', LAUNCHD_PLIST], { stdio: 'ignore' }); } catch { /* not loaded yet */ }
+  try { spawnSync('launchctl', ['load', '-w', LAUNCHD_PLIST], { stdio: 'ignore' }); } catch { /* deferred to next login */ }
+  dirtyStep(SYM_OK, 'startup entry', `LaunchAgent ${LAUNCHD_LABEL} — daemon starts at login`);
+}
+
+function removeStartupEntryMac() {
+  try { spawnSync('launchctl', ['unload', '-w', LAUNCHD_PLIST], { stdio: 'ignore' }); } catch { /* not loaded */ }
+  try { if (existsSync(LAUNCHD_PLIST)) { unlinkSync(LAUNCHD_PLIST); step(SYM_OK, 'startup entry', 'removed (LaunchAgent)'); } }
+  catch { /* already gone */ }
+}
+
+// ── Linux: systemd --user service (starts at login) ───────────────────────────
+function addStartupEntryLinux(exePath) {
+  const unit = systemdUnit(daemonLaunch(exePath));
+  try {
+    mkdirSync(dirname(SYSTEMD_UNIT), { recursive: true });
+    writeFileSync(SYSTEMD_UNIT, unit);
+  } catch (e) {
+    step(SYM_WARN, 'startup entry', `couldn't write systemd unit (${e.message}) — the session self-heal still starts the daemon`, console.warn);
+    return;
+  }
+  // Enable + start now. Non-fatal if there's no systemd --user session (some
+  // containers / minimal WSL): the SessionStart self-heal still brings it up.
+  systemctlUser(['daemon-reload']);
+  const r = systemctlUser(['enable', '--now', SYSTEMD_UNIT_NAME]);
+  if (r && r.status === 0) dirtyStep(SYM_OK, 'startup entry', `systemd --user ${SYSTEMD_UNIT_NAME} — daemon starts at login`);
+  else dirtyStep(SYM_INFO, 'startup entry', `systemd unit written — enable with: systemctl --user enable --now ${SYSTEMD_UNIT_NAME}`);
+}
+
+function removeStartupEntryLinux() {
+  systemctlUser(['disable', '--now', SYSTEMD_UNIT_NAME]);
+  try { if (existsSync(SYSTEMD_UNIT)) { unlinkSync(SYSTEMD_UNIT); step(SYM_OK, 'startup entry', 'removed (systemd unit)'); } }
+  catch { /* already gone */ }
+  systemctlUser(['daemon-reload']);
+}
+
 export async function addStartupEntry(exePath) {
+  if (process.platform === 'darwin') return addStartupEntryMac(exePath);
+  if (process.platform === 'linux') return addStartupEntryLinux(exePath);
+  if (process.platform !== 'win32') {
+    if (runDirty) step(SYM_INFO, 'startup entry', `skipped — no login-autostart for ${process.platform}`);
+    return;
+  }
+  // ── Windows: HKCU Run-key + windowless .vbs shim ──
   // The packaged exe is a console-subsystem node.exe, so a bare Run-key entry
   // (`"<exe>" daemon`) makes Explorer pop a console window at every login that
   // persists for the daemon's whole (weeks-long) life — closing it kills the
@@ -178,6 +302,9 @@ export async function addStartupEntry(exePath) {
 }
 
 export async function removeStartupEntry() {
+  if (process.platform === 'darwin') return removeStartupEntryMac();
+  if (process.platform === 'linux') return removeStartupEntryLinux();
+  if (process.platform !== 'win32') return;
   try {
     await regCommand(['delete', STARTUP_KEY, '/v', STARTUP_VALUE, '/f']);
     step(SYM_OK, 'startup entry', 'removed');
@@ -557,6 +684,43 @@ function warnIfStale() {
   } catch { /* offline or npm missing — a version check must never block setup */ }
 }
 
+// Self-heal an install across an update. There is NO npm install script (by
+// design — `npm install` must run nothing), so an `npm update` swaps the files
+// but re-wires nothing: a long-lived user keeps stale hook commands and old
+// config and never gets the new behaviour. The daemon — itself brought up by the
+// SessionStart self-heal — calls this on startup: when the stamped version
+// differs from the running one, re-wire the hooks (their command/path drifts
+// across versions) and migrate config to the current shape, then stamp the
+// version. Best-effort and quiet by default; never throws into the caller.
+// Returns { changed, from, rewired }.
+export function selfHealOnUpdate({ exePath = null, silent = true } = {}) {
+  let from = null;
+  try { from = (readFileSync(VERSION_STAMP, 'utf8') || '').trim() || null; } catch { /* first run / unreadable — treat as needing a heal */ }
+  if (from === VERSION) return { changed: false, from, rewired: false };
+  const exe = exePath || ((IS_PACKAGED && existsSync(CANONICAL_EXE)) ? CANONICAL_EXE : process.execPath);
+  let rewired = false;
+  try { rewired = installHooks(exe, { silent }); } catch { /* best-effort — a hook re-wire must never block daemon startup */ }
+  try { migrateConfig({ silent }); } catch { /* best-effort */ }
+  // Carry the login autostart forward too — an update should leave the daemon
+  // coming up at login, not only on the next Claude Code session — unless the
+  // user opted out with autostart:false. Best-effort + fire-and-forget; a
+  // failure just falls back to the SessionStart self-heal. In the detached
+  // daemon, addStartupEntry's console output lands in ignored stdio. This is
+  // disclosed in SECURITY.md (a login-autostart service can appear on update).
+  let autostart = false;
+  try {
+    if (readJson(CONFIG_PATH, {}).autostart !== false) {
+      autostart = true;
+      Promise.resolve(addStartupEntry(exe)).catch(() => {});
+    }
+  } catch { /* best-effort */ }
+  try {
+    mkdirSync(dirname(VERSION_STAMP), { recursive: true });
+    writeFileSync(VERSION_STAMP, VERSION + '\n');
+  } catch { /* unwritable — we'll just self-heal again next start, which is harmless (idempotent) */ }
+  return { changed: true, from, rewired, autostart };
+}
+
 export async function install({ exePath, withStartup = true } = {}) {
   resetRun();
   console.log('');
@@ -604,12 +768,11 @@ export async function install({ exePath, withStartup = true } = {}) {
   // row lands under this heading; setupOutro() then closes the screen.
   phase('daemon');
   if (withStartup) {
-    if (process.platform === 'win32') {
-      try { await addStartupEntry(target); }
-      catch (e) { step(SYM_WARN, 'startup entry', `failed: ${e.message}`, console.warn); }
-    } else if (runDirty) {
-      step(SYM_INFO, 'startup entry', 'skipped — login autostart is Windows-only');
-    }
+    // Cross-platform login autostart: Windows Run-key, macOS LaunchAgent, Linux
+    // systemd --user. Best-effort — a failure leaves the SessionStart self-heal
+    // as the (already reliable) fallback, so setup never fails on this.
+    try { await addStartupEntry(target); }
+    catch (e) { step(SYM_WARN, 'startup entry', `failed: ${e.message} — session self-heal still covers it`, console.warn); }
   }
   // Nothing changed: the checklist above stayed silent, so say so in one line.
   if (!runDirty && probe.ok) {
@@ -640,7 +803,7 @@ export async function uninstall() {
   console.log(`  ${c.bold}${c.magenta}◆ claude-rpc uninstall${c.reset}`);
   console.log('');
   uninstallHooks();
-  if (process.platform === 'win32') await removeStartupEntry();
+  await removeStartupEntry();
   console.log('');
   console.log(`  ${SYM_OK}  ${c.bold}uninstalled${c.reset} — config at ${c.cyan}${USER_CONFIG_DIR}${c.reset} ${c.dim}left intact; delete it manually if you want.${c.reset}`);
   console.log('');

package/src/paths.js

@@ -91,6 +91,10 @@ export const DATA_DIR = join(homedir(), '.claude-rpc');
 export const AGGREGATE_PATH = join(DATA_DIR, 'aggregate.json');
 export const SCAN_CACHE_PATH = join(DATA_DIR, 'scan-cache.json');
 export const EVENTS_LOG_PATH = join(DATA_DIR, 'events.jsonl');
+// Last claude-rpc version that ran the on-update self-heal (hook re-wire + config
+// migrate). Persistent (under ~/.claude-rpc) so an update is detected across
+// reboots — see install.selfHealOnUpdate.
+export const VERSION_STAMP = join(DATA_DIR, 'version');
 export const CLAUDE_HOME = join(homedir(), '.claude');
 export const CLAUDE_PROJECTS = join(CLAUDE_HOME, 'projects');
 export const CLAUDE_SETTINGS = join(CLAUDE_HOME, 'settings.json');

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