claude-rpc 0.20.4 → 0.22.0

package/README.md

@@ -25,7 +25,7 @@
 [![Node 18+](https://img.shields.io/badge/node-%3E%3D18-43853d.svg?logo=node.js&logoColor=white)](https://nodejs.org)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-hooks-d97757.svg)](https://claude.com/claude-code)
 [![Discord RPC](https://img.shields.io/badge/Discord-RPC-5865F2.svg?logo=discord&logoColor=white)](https://discord.com/developers/docs/topics/rpc)
-[![Release](https://img.shields.io/github/v/release/rar-file/claude-rpc?color=4c1)](https://github.com/rar-file/claude-rpc/releases/latest)
+[![Release](https://img.shields.io/npm/v/claude-rpc?color=4c1&label=release&logo=npm&logoColor=white)](https://github.com/rar-file/claude-rpc/releases/latest)
 [![npm downloads](https://img.shields.io/npm/dm/claude-rpc?color=cb3837&logo=npm&logoColor=white&label=downloads)](https://www.npmjs.com/package/claude-rpc)
 
 </div>
@@ -139,7 +139,22 @@ The web dashboard pushes updates via SSE; the TUI refreshes on a 3-second tick.
 
 ### beyond your machine
 
-Shields-style badges and a poster-style summary card you can paste into a README or a Discord message:
+Shields-style badges and a poster-style summary card you can paste into a README or a Discord message. The fastest path is one command:
+
+```sh
+claude-rpc readme                 # prints paste-ready README badge markdown
+claude-rpc readme --raw | pbcopy  # straight to your clipboard
+```
+
+**Live badges, paste once.** With a public profile (`claude-rpc profile set --handle <you> && claude-rpc profile on`), your stats are served as always-current badges from the community worker — no `gh`, no gist, nothing to re-run:
+
+```md
+[![Claude Code hours](https://claude-rpc-totals.claude-rpc.workers.dev/badge/<you>.svg?metric=hours)](https://claude-rpc.vercel.app/?ref=badge)
+```
+
+`metric=` is one of `tokens · sessions · hours · streak` (optional `&label=` to retitle). Your profile page at `/u/<you>` has a one-click "copy" for the same block. The badge refreshes itself as the daemon flushes your profile (~every 30 min).
+
+Prefer to render locally? `badge`/`card`/`calendar`/`github-stat` all write SVG, and `--gist` self-hosts a live one:
 
 ```sh
 claude-rpc badge --metric hours  --range 7d   --out claude-hours.svg
@@ -258,6 +273,17 @@ 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.
 
+## claude code plugin
+
+Prefer to install from inside Claude Code? There's a [plugin](plugin/) for that:
+
+```text
+/plugin marketplace add rar-file/claude-rpc
+/plugin install claude-rpc@claude-rpc
+```
+
+It's a thin bootstrapper — on the first session it just runs `npx claude-rpc@latest setup` for you (the same install as above), then stays out of the way. macOS / Linux / WSL; on Windows use the portable exe. Nothing extra is added to your sessions — the plugin is a single `SessionStart` hook with no model-context cost.
+
 ## commands
 
 `claude-rpc --help` lists them all — and after `setup` you rarely need any.
@@ -286,6 +312,7 @@ The full default config is in [`src/default-config.js`](src/default-config.js)
 | `github-stat`    | Embeddable profile stat card (`--handle` `--out` `--gist`) |
 | `calendar`       | Year activity heatmap SVG (`--out` `--gist`) |
 | `session-card`   | Recap card for the current session (`--out`) |
+| `readme`         | Paste-ready README badge markdown for your profile (`--raw` to pipe) |
 | `statusline`     | One-line status for tmux/shell prompts (`--template`) |
 | `mcp install`    | Wire the stats MCP server into Claude Code (one command) |
 | `mcp`            | Run the MCP server (stdio) for Claude Code |

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.22.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/cli.js

@@ -1057,6 +1057,67 @@ async function doSessionCard(argv) {
   } else process.stdout.write(svg);
 }
 
+// `claude-rpc readme` — paste-ready markdown for putting your live Claude Code
+// stats in a README. Pure printer: reads config + the worker endpoint, never
+// hits the network. The live badges track your published profile and refresh
+// themselves (no gist, no `gh`, no re-running). `--raw` prints just the
+// markdown so you can pipe it straight to a clipboard tool.
+function doReadme(argv) {
+  const raw = argv.includes('--raw') || argv.includes('--plain');
+  const cfg = loadConfig();
+  const endpoint = (cfg.community?.endpoint || 'https://claude-rpc-totals.claude-rpc.workers.dev').replace(/\/+$/, '');
+  const site = 'https://claude-rpc.vercel.app';
+  const profile = cfg.profile || {};
+  const handle = profile.handle;
+  const live = !!profile.enabled && lb.isValidHandle(handle);
+  const metrics = [
+    ['hours',  'Claude Code hours'],
+    ['streak', 'Claude Code streak'],
+    ['tokens', 'Claude Code tokens'],
+  ];
+  const liveMd = (h) => metrics
+    .map(([m, alt]) => `[![${alt}](${endpoint}/badge/${h}.svg?metric=${m})](${site}/?ref=badge)`)
+    .join('\n');
+
+  // Raw mode: just the markdown, for `claude-rpc readme --raw | pbcopy`.
+  if (raw) {
+    process.stdout.write(live
+      ? liveMd(handle) + '\n'
+      : '<!-- live badges need a public profile: claude-rpc profile set --handle <name> && claude-rpc profile on -->\n');
+    return;
+  }
+
+  console.log('');
+  console.log(`  ${c.bold}${c.magenta}◆ README badges${c.reset}`);
+  console.log('');
+
+  if (live) {
+    console.log(`  ${c.dim}Live badges for ${c.reset}${c.cyan}@${handle}${c.reset}${c.dim} — paste anywhere; they refresh as you work:${c.reset}`);
+    console.log('');
+    for (const line of liveMd(handle).split('\n')) console.log(`    ${line}`);
+    console.log('');
+    console.log(`  ${c.dim}Pick any metric:${c.reset} ${c.cyan}tokens · sessions · hours · streak${c.reset}`);
+    console.log(`  ${c.dim}One-click copy + shareable page:${c.reset} ${c.cyan}${site}/u/${handle}${c.reset}`);
+    console.log(`  ${c.dim}Straight to clipboard:${c.reset} ${c.cyan}claude-rpc readme --raw${c.reset}${c.dim} | pbcopy${c.reset}`);
+  } else {
+    console.log(`  ${c.dim}A live, always-current badge needs a public profile. Turn one on:${c.reset}`);
+    console.log(`    ${c.cyan}claude-rpc profile set --handle <name> && claude-rpc profile on${c.reset}`);
+    console.log('');
+    console.log(`  ${c.dim}Then your badges live here (self-refreshing — paste once):${c.reset}`);
+    console.log(`    ${c.cyan}${endpoint}/badge/<handle>.svg?metric=hours${c.reset}`);
+  }
+
+  console.log('');
+  console.log(`  ${c.dim}── self-host on a GitHub gist instead (works without a profile) ──${c.reset}`);
+  console.log(`    ${c.cyan}claude-rpc badge --metric hours --gist${c.reset}   ${c.dim}# prints README markdown${c.reset}`);
+  console.log('');
+  console.log(`  ${c.dim}Shareable cards:${c.reset}`);
+  console.log(`    ${c.cyan}claude-rpc card --range year --out year.svg${c.reset}   ${c.dim}# poster${c.reset}`);
+  console.log(`    ${c.cyan}claude-rpc calendar --gist${c.reset}                    ${c.dim}# live year heatmap${c.reset}`);
+  console.log(`    ${c.cyan}claude-rpc github-stat --gist${c.reset}                 ${c.dim}# profile stat card${c.reset}`);
+  console.log('');
+}
+
 // MCP server — expose stats to Claude Code over stdio. Long-running; never
 // writes to stdout except JSON-RPC frames.
 async function doMcp() {
@@ -1942,6 +2003,7 @@ function help() {
     ['statusline', 'One-line status for tmux/shell prompts (--template)'],
     ['calendar',  'Year activity heatmap SVG (--out --gist)'],
     ['session-card', 'Recap card for the current session (--out)'],
+    ['readme',    'Paste-ready README badges for your profile (--raw to pipe)'],
     ['mcp install', 'Wire the stats MCP server into Claude Code (one command)'],
     ['mcp uninstall', 'Remove the stats MCP server from Claude Code'],
     ['mcp',       'Run the MCP server (stdio) — exposes your stats to Claude'],
@@ -2097,6 +2159,7 @@ process.on('unhandledRejection', (e) => {
     case 'statusline': doStatusline(process.argv.slice(3)); break;
     case 'calendar':  await doCalendar(process.argv.slice(3)); break;
     case 'session-card': await doSessionCard(process.argv.slice(3)); break;
+    case 'readme':    doReadme(process.argv.slice(3)); break;
     case 'mcp': {
       const sub = process.argv[3];
       if (sub === 'install')   { doMcpInstall(process.argv.slice(4)); break; }

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.22.0';
 
 function readPkgVersion() {
   try {