claude-rpc 0.3.8

package/src/git.js

@@ -0,0 +1,74 @@
+// Cheap, cached lookups into a project's .git directory.
+//
+// Everything here reads `.git/config` or `.git/HEAD` directly — no shell-out,
+// no spawn, no recursion up parent dirs. The daemon calls these on every
+// presence push, so each result is cached per-cwd with a short TTL.
+//
+// The detached-HEAD case (HEAD contains a raw SHA, not `ref: refs/heads/...`)
+// returns an empty branch — template `requires` will hide the branch frame.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+const TTL_MS = 5 * 60 * 1000;
+const cache = new Map(); // cwd → { ts, github, branch, repo }
+
+function fresh(entry) {
+  return entry && (Date.now() - entry.ts) < TTL_MS;
+}
+
+function readGitInfo(cwd) {
+  const out = { github: null, branch: '', repo: '' };
+  if (!cwd) return out;
+
+  // Repo name fallback is always the cwd basename — overwritten below if we
+  // find a github origin.
+  out.repo = basename(cwd) || '';
+
+  const gitDir = join(cwd, '.git');
+  if (!existsSync(gitDir)) return out;
+
+  // origin URL → github URL + repo name.
+  try {
+    const cfg = readFileSync(join(gitDir, 'config'), 'utf8');
+    const m = cfg.match(/\[remote\s+"origin"\][^\[]*?url\s*=\s*([^\r\n]+)/i);
+    if (m) {
+      const raw = m[1].trim();
+      const ssh = raw.match(/^git@github\.com:([^\s]+?)(?:\.git)?$/i);
+      if (ssh) {
+        out.github = `https://github.com/${ssh[1]}`;
+        out.repo = basename(ssh[1]);
+      } else if (/^https?:\/\/github\.com\//i.test(raw)) {
+        out.github = raw.replace(/\.git$/i, '');
+        out.repo = basename(out.github);
+      } else {
+        // Non-github remote — still pull the repo name out of the URL.
+        const tail = raw.replace(/\.git$/i, '').replace(/[\\/]+$/, '');
+        const leaf = tail.split(/[\\/:]/).filter(Boolean).pop();
+        if (leaf) out.repo = leaf;
+      }
+    }
+  } catch {}
+
+  // HEAD → branch (or empty when detached).
+  try {
+    const head = readFileSync(join(gitDir, 'HEAD'), 'utf8').trim();
+    const ref = head.match(/^ref:\s+refs\/heads\/(.+)$/);
+    if (ref) out.branch = ref[1].trim();
+  } catch {}
+
+  return out;
+}
+
+function lookup(cwd) {
+  if (!cwd) return { github: null, branch: '', repo: '' };
+  const cached = cache.get(cwd);
+  if (fresh(cached)) return cached;
+  const info = readGitInfo(cwd);
+  cache.set(cwd, { ts: Date.now(), ...info });
+  return info;
+}
+
+export function detectGithubUrl(cwd) { return lookup(cwd).github; }
+export function detectGitBranch(cwd) { return lookup(cwd).branch; }
+export function detectGitRepo(cwd)   { return lookup(cwd).repo; }

package/src/hook.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import { readFileSync, appendFileSync, existsSync, mkdirSync, statSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { updateState, resetState, pushUnique, shortFile } from './state.js';
+import { EVENTS_LOG_PATH } from './paths.js';
+
+const EVENTS_LOG_ROTATE_BYTES = 5 * 1024 * 1024;
+
+function appendEvent(entry) {
+  try {
+    mkdirSync(dirname(EVENTS_LOG_PATH), { recursive: true });
+    if (existsSync(EVENTS_LOG_PATH)) {
+      const st = statSync(EVENTS_LOG_PATH);
+      if (st.size > EVENTS_LOG_ROTATE_BYTES) {
+        renameSync(EVENTS_LOG_PATH, EVENTS_LOG_PATH + '.1');
+      }
+    }
+    appendFileSync(EVENTS_LOG_PATH, JSON.stringify(entry) + '\n');
+  } catch {}
+}
+
+function readStdin() {
+  try {
+    return readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function parseInput() {
+  const raw = readStdin();
+  if (!raw.trim()) return {};
+  try { return JSON.parse(raw); } catch { return {}; }
+}
+
+// Handle a single hook event. Exported so the bundled exe can dispatch
+// directly (avoids spawning a child process per hook).
+export function processHookEvent(event, input = {}) {
+  const now = Date.now();
+
+  function setActivity(patch) {
+    updateState((s) => {
+      Object.assign(s, patch);
+      s.lastActivity = now;
+      // Any hook firing means Claude Code is alive — clear the closed flag
+      // in case a prior SessionEnd from a sibling session set it.
+      s.claudeClosed = false;
+      if (!s.sessionStart) s.sessionStart = now;
+      return s;
+    });
+  }
+
+  switch (event) {
+    case 'SessionStart': {
+      resetState({
+        cwd: input.cwd || process.cwd(),
+        model: input.model?.id || input.model || 'claude',
+        status: 'idle',
+      });
+      break;
+    }
+    case 'UserPromptSubmit': {
+      updateState((s) => {
+        s.messages += 1;
+        s.lastUserPrompt = now;
+        s.lastActivity = now;
+        s.status = 'thinking';
+        s.claudeClosed = false;
+        if (!s.sessionStart) s.sessionStart = now;
+        if (input.cwd) s.cwd = input.cwd;
+        return s;
+      });
+      break;
+    }
+    case 'PreToolUse': {
+      const toolName = input.tool_name || input.toolName || 'tool';
+      const toolInput = input.tool_input || input.toolInput || {};
+      const file = toolInput.file_path || toolInput.path || toolInput.notebook_path || null;
+      updateState((s) => {
+        s.tools += 1;
+        s.toolBreakdown[toolName] = (s.toolBreakdown[toolName] || 0) + 1;
+        s.currentTool = toolName;
+        s.currentFile = shortFile(file);
+        s.status = 'working';
+        s.lastActivity = now;
+        s.claudeClosed = false;
+        if (!s.sessionStart) s.sessionStart = now;
+        if (file && (toolName === 'Read' || toolName === 'NotebookEdit')) {
+          s.filesOpened = pushUnique(s.filesOpened, file);
+          if (toolName === 'Read') s.filesRead = pushUnique(s.filesRead, file);
+        }
+        return s;
+      });
+      break;
+    }
+    case 'PostToolUse': {
+      const toolName = input.tool_name || input.toolName || '';
+      const toolInput = input.tool_input || input.toolInput || {};
+      const file = toolInput.file_path || toolInput.path || null;
+      updateState((s) => {
+        s.currentTool = null;
+        s.lastActivity = now;
+        s.claudeClosed = false;
+        if (!s.sessionStart) s.sessionStart = now;
+        if (file && (toolName === 'Write' || toolName === 'Edit' || toolName === 'NotebookEdit')) {
+          s.filesEdited = pushUnique(s.filesEdited, file);
+          s.filesOpened = pushUnique(s.filesOpened, file);
+        }
+        const usage = input.tool_response?.usage || input.usage;
+        if (usage) {
+          s.tokens.input += usage.input_tokens || 0;
+          s.tokens.output += usage.output_tokens || 0;
+          s.tokens.cacheRead += usage.cache_read_input_tokens || 0;
+          s.tokens.cacheWrite += usage.cache_creation_input_tokens || 0;
+        }
+        return s;
+      });
+      break;
+    }
+    case 'Notification': {
+      updateState((s) => {
+        s.status = 'notification';
+        s.lastNotification = now;
+        s.lastActivity = now;
+        s.claudeClosed = false;
+        s.currentTool = null;
+        s.currentFile = null;
+        if (!s.sessionStart) s.sessionStart = now;
+        return s;
+      });
+      appendEvent({ type: 'notification', ts: now, cwd: input.cwd || null });
+      break;
+    }
+    case 'SessionEnd': {
+      // Authoritative "Claude Code is gone" signal — don't wait on the
+      // staleSessionMin timeout. applyIdle short-circuits to stale when it
+      // sees claudeClosed=true. Any subsequent hook from another live
+      // session will flip the flag back to false.
+      updateState((s) => {
+        s.status = 'stale';
+        s.claudeClosed = true;
+        s.currentTool = null;
+        s.currentFile = null;
+        s.lastActivity = now;
+        return s;
+      });
+      break;
+    }
+    case 'Stop':
+    case 'SubagentStop':
+    default: {
+      setActivity({ status: 'idle', currentTool: null, currentFile: null });
+    }
+  }
+}
+
+// Stdin-driven CLI form: read JSON event payload from stdin, dispatch, ack.
+export function runHookCli(event) {
+  processHookEvent(event, parseInput());
+  process.stdout.write(JSON.stringify({ continue: true }));
+}
+
+// Run directly when invoked as `node src/hook.js <event>`. Detection is based
+// on whether argv[1] ends in this filename — when imported (e.g. by cli.js),
+// argv[1] won't match.
+const argv1 = (process.argv[1] || '').replace(/\\/g, '/').toLowerCase();
+if (argv1.endsWith('/src/hook.js') || argv1.endsWith('/hook.js')) {
+  runHookCli(process.argv[2] || 'unknown');
+}

package/src/insights.js

@@ -0,0 +1,138 @@
+// Generate 3–5 short, contextual insight lines from an aggregate.json snapshot.
+// Used by `claude-rpc insights`, the web `/api/insights` route, and the TUI.
+// Pure functions — no I/O, no globals beyond Date.
+
+import { dayKey, weekKey } from './scanner.js';
+import { fmtCost } from './pricing.js';
+
+const WEEKDAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+
+function fmtHours(ms) {
+  if (!ms || ms < 0) return '0h';
+  const hours = ms / 3_600_000;
+  if (hours < 1) return `${Math.round(hours * 60)}m`;
+  if (hours < 10) return `${hours.toFixed(1)}h`;
+  return `${Math.round(hours)}h`;
+}
+
+function fmtNum(n) {
+  if (!n) return '0';
+  if (n < 1000) return `${n}`;
+  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
+  return `${(n / 1_000_000).toFixed(2)}M`;
+}
+
+function pct(n) {
+  const sign = n >= 0 ? '+' : '−';
+  return `${sign}${Math.round(Math.abs(n) * 100)}%`;
+}
+
+// Sum activeMs across the last `days` days (inclusive of today).
+function windowActive(byDay, days, offset = 0) {
+  let total = 0;
+  const today = new Date(); today.setHours(0, 0, 0, 0);
+  for (let i = offset; i < offset + days; i++) {
+    const d = new Date(today); d.setDate(d.getDate() - i);
+    total += (byDay?.[dayKey(d.getTime())] || {}).activeMs || 0;
+  }
+  return total;
+}
+
+export function generateInsights(aggregate, opts = {}) {
+  const a = aggregate || {};
+  const out = [];
+
+  if (!a.byDay || !Object.keys(a.byDay).length) {
+    return ['Not enough data yet — keep coding and check back tomorrow.'];
+  }
+
+  // 1. Trend: last 7 days vs the 7 before it.
+  const last7 = windowActive(a.byDay, 7, 0);
+  const prev7 = windowActive(a.byDay, 7, 7);
+  if (last7 || prev7) {
+    if (prev7 > 0) {
+      const delta = (last7 - prev7) / prev7;
+      if (Math.abs(delta) >= 0.10) {
+        const dir = delta > 0 ? 'above' : 'below';
+        out.push(`You're ${pct(delta)} ${dir} last week — ${fmtHours(last7)} vs ${fmtHours(prev7)}.`);
+      } else {
+        out.push(`Steady week — ${fmtHours(last7)} active, on par with the previous 7 days.`);
+      }
+    } else if (last7 > 0) {
+      out.push(`Fresh momentum — ${fmtHours(last7)} active this past week.`);
+    }
+  }
+
+  // 2. Peak weekday.
+  if (a.byWeekday && Object.keys(a.byWeekday).length) {
+    let best = null;
+    for (const [wd, data] of Object.entries(a.byWeekday)) {
+      if (!best || data.activeMs > best.ms) best = { wd: Number(wd), ms: data.activeMs };
+    }
+    if (best && best.ms > 0) {
+      out.push(`Peak weekday is ${WEEKDAYS[best.wd]} — ${fmtHours(best.ms)} all-time.`);
+    }
+  }
+
+  // 3. Cost pace (month-to-date forecast).
+  if (a.estimatedCost && a.byDay) {
+    const now = new Date();
+    const yearMonth = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
+    let mtd = 0;
+    for (const [k, day] of Object.entries(a.byDay)) {
+      if (k.startsWith(yearMonth)) mtd += day.cost || 0;
+    }
+    if (mtd > 0) {
+      const daysIn = now.getDate();
+      const daysInMonth = new Date(now.getFullYear(), now.getMonth() + 1, 0).getDate();
+      const forecast = (mtd / daysIn) * daysInMonth;
+      out.push(`Month-to-date estimate: ${fmtCost(mtd)} — pace projects ${fmtCost(forecast)} for the month.`);
+    }
+  }
+
+  // 4. Top hotspot.
+  if (a.topEditedFiles && a.topEditedFiles.length) {
+    const top = a.topEditedFiles[0];
+    const name = top.path.split(/[\\/]/).filter(Boolean).pop();
+    out.push(`Hotspot: ${name} with ${fmtNum(top.count)} edits.`);
+  }
+
+  // 5. Streak milestone tease.
+  if (a.streak >= 3) {
+    const targets = [7, 14, 30, 60, 100, 365];
+    const next = targets.find((t) => t > a.streak);
+    if (next) {
+      const remaining = next - a.streak;
+      out.push(`${a.streak}-day streak — ${remaining} ${remaining === 1 ? 'day' : 'days'} to ${next}.`);
+    } else {
+      out.push(`${a.streak}-day streak — beyond every milestone we track. Incredible.`);
+    }
+  } else if (a.longestStreak >= 7) {
+    out.push(`Longest streak so far: ${a.longestStreak} days. Today could start the next one.`);
+  }
+
+  // 6. Top language / framework.
+  if (a.languages) {
+    const top = Object.entries(a.languages).sort((x, y) => y[1].edits - x[1].edits)[0];
+    if (top) {
+      out.push(`Most edits land in ${top[0]} — ${fmtNum(top[1].edits)} across ${fmtNum(top[1].files)} files.`);
+    }
+  }
+
+  // 7. Subagent usage (where it differs interestingly from defaults).
+  if (a.subagents && Object.keys(a.subagents).length) {
+    const top = Object.entries(a.subagents).sort((x, y) => y[1] - x[1])[0];
+    if (top && top[1] >= 3) {
+      out.push(`Favorite subagent: ${top[0]} — invoked ${top[1]} times.`);
+    }
+  }
+
+  // 8. Notification frequency (only when high).
+  if (a.notifications && a.notifications > 20) {
+    out.push(`${a.notifications} notifications — Claude has paused for you that many times.`);
+  }
+
+  // Trim to a tidy 5 — biggest signals first (sort is already roughly priority).
+  const limit = opts.limit ?? 5;
+  return out.slice(0, limit);
+}

package/src/install.js

@@ -0,0 +1,280 @@
+// One-shot installer logic invoked by the bundled exe.
+// Seeds %APPDATA%\claude-rpc\config.json, points Claude Code's hooks at the
+// exe, and registers a Windows startup entry so the daemon comes up on login.
+
+import {
+  existsSync, mkdirSync, readFileSync, writeFileSync,
+  copyFileSync, chmodSync, renameSync, statSync,
+  readdirSync, unlinkSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import {
+  CLAUDE_SETTINGS, CONFIG_PATH, USER_CONFIG_DIR,
+  HOOK_SCRIPT, IS_PACKAGED,
+  CANONICAL_EXE, CANONICAL_INSTALL_DIR, CANONICAL_EXE_NAME,
+} from './paths.js';
+import { DEFAULT_CONFIG } from './default-config.js';
+
+const STARTUP_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run';
+const STARTUP_VALUE = 'ClaudeRPC';
+
+const EVENTS = [
+  'SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse',
+  'Stop', 'SubagentStop', 'Notification', 'SessionEnd',
+];
+
+function readJson(p, fb) {
+  try { return JSON.parse(readFileSync(p, 'utf8')); }
+  catch { return fb; }
+}
+
+function writeJson(p, d) {
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(d, null, 2));
+}
+
+function isOurHookCommand(cmd) {
+  if (!cmd) return false;
+  return /claude-rpc/i.test(cmd) || /hook\.js/i.test(cmd);
+}
+
+export function installHooks(exePath) {
+  const settings = readJson(CLAUDE_SETTINGS, {});
+  settings.hooks = settings.hooks || {};
+  // Packaged: `"<exe>" hook <event>`. Dev: `node "<src/hook.js>" <event>`.
+  const cmdFor = IS_PACKAGED
+    ? (event) => `"${exePath}" hook ${event}`
+    : (event) => `node "${HOOK_SCRIPT.replace(/\\/g, '/')}" ${event}`;
+
+  for (const event of EVENTS) {
+    const bucket = settings.hooks[event] = settings.hooks[event] || [];
+    const wanted = cmdFor(event);
+    const existingEntry = bucket.find((b) =>
+      Array.isArray(b.hooks) && b.hooks.some((h) => isOurHookCommand(h.command))
+    );
+    if (existingEntry) {
+      existingEntry.hooks = existingEntry.hooks.map((h) =>
+        isOurHookCommand(h.command) ? { ...h, command: wanted } : h
+      );
+    } else {
+      bucket.push({ matcher: '', hooks: [{ type: 'command', command: wanted }] });
+    }
+  }
+  writeJson(CLAUDE_SETTINGS, settings);
+  console.log(`  hooks → ${CLAUDE_SETTINGS}`);
+}
+
+export function uninstallHooks() {
+  const settings = readJson(CLAUDE_SETTINGS, {});
+  if (!settings.hooks) return;
+  for (const event of EVENTS) {
+    const bucket = settings.hooks[event];
+    if (!Array.isArray(bucket)) continue;
+    settings.hooks[event] = bucket
+      .map((entry) => ({ ...entry, hooks: (entry.hooks || []).filter((h) => !isOurHookCommand(h.command)) }))
+      .filter((entry) => (entry.hooks || []).length > 0);
+    if (settings.hooks[event].length === 0) delete settings.hooks[event];
+  }
+  writeJson(CLAUDE_SETTINGS, settings);
+  console.log(`  hooks removed from ${CLAUDE_SETTINGS}`);
+}
+
+function regCommand(args) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('reg', args, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    let err = '';
+    proc.stderr.on('data', (d) => err += d.toString());
+    proc.on('error', reject);
+    proc.on('close', (code) => code === 0 ? resolve() : reject(new Error(err || `reg.exe exit ${code}`)));
+  });
+}
+
+export async function addStartupEntry(exePath) {
+  await regCommand([
+    'add', STARTUP_KEY,
+    '/v', STARTUP_VALUE,
+    '/t', 'REG_SZ',
+    '/d', `"${exePath}" daemon`,
+    '/f',
+  ]);
+  console.log(`  startup → HKCU\\...\\Run\\${STARTUP_VALUE}`);
+}
+
+export async function removeStartupEntry() {
+  try {
+    await regCommand(['delete', STARTUP_KEY, '/v', STARTUP_VALUE, '/f']);
+    console.log(`  startup entry removed`);
+  } catch {
+    // Already absent — fine.
+  }
+}
+
+function samePath(a, b) {
+  if (!a || !b) return false;
+  try {
+    const ra = resolve(a);
+    const rb = resolve(b);
+    return process.platform === 'win32'
+      ? ra.toLowerCase() === rb.toLowerCase()
+      : ra === rb;
+  } catch { return false; }
+}
+
+// Best-effort sweep of stale `.old-<ts>` siblings left behind by a prior
+// rename-out-of-the-way during an in-place exe replacement.
+function sweepStaleCanonicalBackups() {
+  try {
+    if (!existsSync(CANONICAL_INSTALL_DIR)) return;
+    const prefix = CANONICAL_EXE_NAME + '.old-';
+    for (const name of readdirSync(CANONICAL_INSTALL_DIR)) {
+      if (name.startsWith(prefix)) {
+        try { unlinkSync(join(CANONICAL_INSTALL_DIR, name)); } catch {}
+      }
+    }
+  } catch {}
+}
+
+// Copy the running binary into CANONICAL_EXE if it's not already there.
+// Returns the path that hook entries should point at — canonical on success,
+// the original path as a fallback. Only meaningful in packaged mode.
+export function ensureCanonicalExe(currentExe) {
+  if (!IS_PACKAGED) return currentExe;
+  if (samePath(currentExe, CANONICAL_EXE)) return CANONICAL_EXE;
+  mkdirSync(CANONICAL_INSTALL_DIR, { recursive: true });
+
+  // Skip the copy when canonical already exists AND matches the source —
+  // avoids a needless overwrite (and the Windows running-file gymnastics it
+  // can trigger) on repeated `setup` runs from the same launch point.
+  if (existsSync(CANONICAL_EXE)) {
+    try {
+      const src = statSync(currentExe);
+      const dst = statSync(CANONICAL_EXE);
+      if (src.size === dst.size && Math.abs(src.mtimeMs - dst.mtimeMs) < 2000) {
+        console.log(`  exe already installed → ${CANONICAL_EXE}`);
+        return CANONICAL_EXE;
+      }
+    } catch {}
+  }
+
+  try {
+    // Windows won't let you overwrite a currently-executing file. If
+    // canonical is the running daemon, move it aside first — that succeeds
+    // even while the file handle is open, and Windows will delete the
+    // renamed copy when the process exits.
+    if (process.platform === 'win32' && existsSync(CANONICAL_EXE)) {
+      try { renameSync(CANONICAL_EXE, CANONICAL_EXE + '.old-' + Date.now()); }
+      catch {}
+    }
+    copyFileSync(currentExe, CANONICAL_EXE);
+    if (process.platform !== 'win32') chmodSync(CANONICAL_EXE, 0o755);
+    console.log(`  exe installed → ${CANONICAL_EXE}`);
+    console.log(`  (the copy at ${currentExe} can be safely deleted)`);
+    sweepStaleCanonicalBackups();
+    return CANONICAL_EXE;
+  } catch (e) {
+    console.warn(`  ! failed to copy exe to ${CANONICAL_EXE}: ${e.message}`);
+    console.warn(`    falling back to ${currentExe} — manual updates that change`);
+    console.warn(`    the exe path may require running 'setup' again.`);
+    return currentExe;
+  }
+}
+
+export function seedConfig() {
+  if (existsSync(CONFIG_PATH)) {
+    console.log(`  config exists → ${CONFIG_PATH}`);
+    return false;
+  }
+  mkdirSync(USER_CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(DEFAULT_CONFIG, null, 2));
+  console.log(`  config seeded → ${CONFIG_PATH}`);
+  return true;
+}
+
+// Non-destructive merge of any new top-level keys / presence blocks the
+// shipped DEFAULT_CONFIG has but the user's existing file doesn't.
+//
+// Runs every time install/setup or the packaged default launcher fires,
+// so an upgraded exe pulls in new shape (e.g. v0.3.6's presence.byStatus)
+// without clobbering the user's customizations. Anything the user already
+// has — including a pre-existing byStatus, custom rotation array, custom
+// appName etc. — is left untouched.
+export function migrateConfig() {
+  if (!existsSync(CONFIG_PATH)) return false;
+  let cfg;
+  try { cfg = JSON.parse(readFileSync(CONFIG_PATH, 'utf8')); }
+  catch (e) {
+    console.warn(`  ! could not read config for migration: ${e.message}`);
+    return false;
+  }
+  if (!cfg || typeof cfg !== 'object') return false;
+
+  const added = [];
+
+  // appName (introduced as a template var in v0.3.5).
+  if (!cfg.appName && DEFAULT_CONFIG.appName) {
+    cfg.appName = DEFAULT_CONFIG.appName;
+    added.push('appName');
+  }
+
+  // presence.byStatus (introduced in v0.3.6) — the headline upgrade.
+  // We only seed it when entirely absent. If a user has already started
+  // editing their own byStatus, we leave it alone.
+  cfg.presence = cfg.presence || {};
+  if (!cfg.presence.byStatus && DEFAULT_CONFIG.presence?.byStatus) {
+    cfg.presence.byStatus = JSON.parse(JSON.stringify(DEFAULT_CONFIG.presence.byStatus));
+    added.push('presence.byStatus');
+  }
+
+  // Refresh the lifetime tooltip when the user is on the very old default
+  // ("…{daysSinceFirstLabel}") so they pick up the new streak-aware copy
+  // without us touching anything they've customized.
+  const OLD_LIT = '{modelPretty} · {allHours} on Claude · {daysSinceFirstLabel}';
+  if (cfg.presence.largeImageText === OLD_LIT && DEFAULT_CONFIG.presence?.largeImageText) {
+    cfg.presence.largeImageText = DEFAULT_CONFIG.presence.largeImageText;
+    added.push('presence.largeImageText');
+  }
+
+  if (added.length === 0) {
+    console.log(`  config up to date → ${CONFIG_PATH}`);
+    return false;
+  }
+  writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2));
+  console.log(`  config migrated  → ${CONFIG_PATH}`);
+  console.log(`    added: ${added.join(', ')}`);
+  return true;
+}
+
+export async function install({ exePath, withStartup = true } = {}) {
+  if (process.platform !== 'win32' && withStartup) {
+    console.warn('Note: startup registration only works on Windows; other steps still run.');
+  }
+  const incoming = exePath || process.execPath;
+  // Canonicalize first so hook + startup entries point at a stable location,
+  // not at the temp/Downloads path the user happened to launch from.
+  const target = ensureCanonicalExe(incoming);
+  console.log('Installing Claude RPC…');
+  // Order matters: seed creates the file if missing, then migrate fills in
+  // any blocks new exe versions added (e.g. presence.byStatus from v0.3.6).
+  seedConfig();
+  migrateConfig();
+  installHooks(target);
+  if (withStartup && process.platform === 'win32') {
+    try { await addStartupEntry(target); }
+    catch (e) { console.warn(`  startup entry failed: ${e.message}`); }
+  }
+  console.log('\nDone.');
+  console.log(`Edit ${CONFIG_PATH} to set your Discord clientId, then either reboot or run:`);
+  console.log(`  "${target}" daemon`);
+}
+
+export async function uninstall() {
+  console.log('Uninstalling Claude RPC…');
+  uninstallHooks();
+  if (process.platform === 'win32') await removeStartupEntry();
+  console.log('\nDone. (Config at %APPDATA%\\claude-rpc\\ left intact — delete manually if you want.)');
+}
+
+export function isInstalled() {
+  return IS_PACKAGED && existsSync(CONFIG_PATH);
+}