sessionboard 0.1.0 → 0.2.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sessionboard",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "AI-judged leaderboard of your Claude Code sessions: rates each session when it ends, keeps your top 3, and exports them redacted for sharing.",
   "author": { "name": "Kush Bang" },
   "keywords": ["sessions", "portfolio", "sharing", "leaderboard"]

package/README.md

@@ -14,11 +14,12 @@ Companies now ask you to share your best AI agent session. After hundreds of cha
 
 ## Install
 
-As a Claude Code plugin, which rates sessions automatically:
+As a Claude Code plugin:
 
 ```
 /plugin marketplace add kbiam/sessionboard
 /plugin install sessionboard@sessionboard
+/sessionboard:setup
 ```
 
 Or as a CLI:
@@ -28,7 +29,7 @@ npm install -g sessionboard
 sessionboard init
 ```
 
-`init` walks you through setup and asks before it changes any Claude Code settings.
+Setup asks a few questions (judge model, board size, words to hide) and asks before it changes any Claude Code settings. Both routes share one rating hook: if one is already installed, setup leaves it alone, so installing both never rates a session twice.
 
 ## Usage
 
@@ -37,9 +38,10 @@ sessionboard dashboard        # open the dashboard at localhost:4317
 sessionboard top              # show your top sessions
 sessionboard share 1 --html   # export your #1 session as a redacted page
 sessionboard config           # change settings
+sessionboard uninstall        # remove the rating hook
 ```
 
-Inside Claude Code: `/sessionboard:dashboard`, `/sessionboard:top`, `/sessionboard:share 1`.
+Inside Claude Code: `/sessionboard:setup`, `/sessionboard:dashboard`, `/sessionboard:top`, `/sessionboard:share 1`.
 
 ## How it works
 

package/bin/sessionboard.mjs

@@ -19,6 +19,9 @@ const INDEX_FILE = path.join(DATA_DIR, 'index.json');
 const CONFIG_FILE = path.join(DATA_DIR, 'config.json');
 const TOP_FILE = path.join(DATA_DIR, 'TOP3.md');
 const EXPORT_DIR = path.join(DATA_DIR, 'exports');
+// The rating hook always runs this copy, so its path survives plugin updates and npm/repo moves.
+const APP_DIR = path.join(DATA_DIR, 'app');
+const APP_FILES = ['bin/sessionboard.mjs', 'lib/dashboard.html', 'package.json'];
 const LOCK_FILE = path.join(DATA_DIR, 'index.lock');
 const CHILD_ENV = 'SESSIONBOARD_CHILD';
 const PARSER_VERSION = 1;
@@ -555,9 +558,34 @@ function patchClaudeSettings(mutate) {
   writeJSON(CLAUDE_SETTINGS, settings);
 }
 
-const pluginInstalled = (settings) => Object.keys(settings.enabledPlugins || {}).some((k) => k.startsWith('sessionboard@'));
-const hookCommand = () => SELF.includes(`${path.sep}_npx${path.sep}`) ? 'npx -y sessionboard hook' : `node "${SELF}" hook`;
 const hasOurHook = (settings) => JSON.stringify(settings.hooks?.SessionEnd || []).includes('sessionboard');
+const hookCommand = () => `node "${path.join(APP_DIR, 'bin', 'sessionboard.mjs')}" hook`;
+
+const versionOf = (dir) => readJSON(path.join(dir, 'package.json'), {}).version || '0.0.0';
+const newer = (a, b) => { const x = a.split('.').map(Number), y = b.split('.').map(Number); for (let i = 0; i < 3; i++) if ((x[i] || 0) !== (y[i] || 0)) return (x[i] || 0) > (y[i] || 0); return false; };
+
+function installAppCopy() {
+  if (path.resolve(ROOT) === path.resolve(APP_DIR)) return;
+  for (const rel of APP_FILES) {
+    fs.mkdirSync(path.dirname(path.join(APP_DIR, rel)), { recursive: true });
+    fs.copyFileSync(path.join(ROOT, rel), path.join(APP_DIR, rel));
+  }
+}
+
+// Any newer sessionboard (plugin update, npm upgrade) that runs refreshes the copy the hook uses.
+function refreshAppCopy() {
+  try { if (fs.existsSync(APP_DIR) && newer(versionOf(ROOT), versionOf(APP_DIR))) installAppCopy(); } catch {}
+}
+
+// Adds the rating hook to settings.json unless one is already there (from any install route).
+function ensureHook(st) {
+  installAppCopy();
+  if (hasOurHook(st)) return false;
+  st.hooks ??= {};
+  st.hooks.SessionEnd ??= [];
+  st.hooks.SessionEnd.push({ hooks: [{ type: 'command', command: hookCommand(), timeout: 10 }] });
+  return true;
+}
 
 // ---------- dashboard ----------
 
@@ -752,7 +780,7 @@ async function configure(flags, { firstRun }) {
     ], 0, 2);
   }
   let hook = false;
-  if (!pluginInstalled(settings) && !hasOurHook(settings)) {
+  if (!hasOurHook(settings)) {
     hook = await ask('Rate sessions automatically when they end? (adds a hook to ~/.claude/settings.json)', [
       { label: 'Yes', value: true, hint: 'recommended' },
       { label: 'No', value: false, hint: 'run `sessionboard update` yourself' },
@@ -760,7 +788,7 @@ async function configure(flags, { firstRun }) {
   }
 
   const cfg = { judge: model !== false, judgeModel: model || cur.judgeModel, rejudgeGrowth, topN, minPrompts, minToolCalls, redactEmails, redactTerms };
-  const hookState = pluginInstalled(settings) ? 'via plugin' : hasOurHook(settings) ? 'installed' : hook ? 'add hook' : 'off (manual updates)';
+  const hookState = hasOurHook(settings) ? 'on (hook already installed)' : hook ? 'add hook' : 'off (manual updates)';
   const keepState = days >= 365 ? `${days} days` : retention ? `${retention} days ${dim(`(was ${days || 30})`)}` : `${days || 30} days ${dim('(unchanged)')}`;
   const row = (k, v) => `${padEnd(dim(k), 20)}${v}`;
   console.log(`\n${box([
@@ -785,11 +813,7 @@ function applySetup({ cfg, retention, hook }) {
   if (retention || hook) {
     patchClaudeSettings((st) => {
       if (retention) st.cleanupPeriodDays = retention;
-      if (hook) {
-        st.hooks ??= {};
-        st.hooks.SessionEnd ??= [];
-        st.hooks.SessionEnd.push({ hooks: [{ type: 'command', command: hookCommand(), timeout: 10 }] });
-      }
+      if (hook) ensureHook(st);
     });
     console.log(`  ${green('✔')} Updated ${tildify(CLAUDE_SETTINGS)} ${dim(`(backup: ${path.basename(CLAUDE_SETTINGS)}.sessionboard-backup)`)}`);
   }
@@ -919,6 +943,7 @@ const HELP = `sessionboard - an AI-judged leaderboard of your Claude Code sessio
   sessionboard pin|unpin|hide|unhide <id> curate the board by hand
   sessionboard show <rank|id>             all stats for one session
   sessionboard config                     change settings interactively (or: config key=value)
+  sessionboard uninstall [--purge]        remove the rating hook (and with --purge, all data)
 
 Data lives in ${tildify(DATA_DIR)}; TOP3.md there is always current.`;
 
@@ -939,6 +964,69 @@ async function main() {
     return;
   }
 
+  if (cmd === 'plugin-start') {
+    // Plugin SessionStart hook: until setup has run, point the user to /sessionboard:setup (once).
+    if (process.env[CHILD_ENV] || loadConfig().initialized) return;
+    const marker = path.join(DATA_DIR, '.setup-nudged');
+    if (fs.existsSync(marker)) return;
+    fs.mkdirSync(DATA_DIR, { recursive: true });
+    fs.writeFileSync(marker, new Date().toISOString());
+    console.log(JSON.stringify({ systemMessage: 'sessionboard is installed. Run /sessionboard:setup to turn on AI rating of your sessions.' }));
+    return;
+  }
+
+  refreshAppCopy();
+
+  // Non-interactive setup used by /sessionboard:setup: Claude asks the questions, then calls these.
+  if (cmd === 'setup-info') {
+    const settings = readJSON(CLAUDE_SETTINGS, {});
+    const index = scan();
+    const sessions = Object.values(index.sessions);
+    return console.log(JSON.stringify({
+      config: loadConfig(),
+      cleanupPeriodDays: settings.cleanupPeriodDays ?? 30,
+      hookInstalled: hasOurHook(settings),
+      sessions: sessions.length,
+      eligible: sessions.filter((x) => x.eligible && !x.missing).length,
+      unrated: sessions.filter((x) => x.eligible && !x.missing && !x.judge).length,
+    }, null, 2));
+  }
+
+  if (cmd === 'setup-apply') {
+    const cur = loadConfig();
+    const num = (v, d) => (v === undefined || v === true ? d : Number(v));
+    const model = flags.judgeModel ?? cur.judgeModel;
+    const cfg = {
+      judge: model !== 'off',
+      judgeModel: model === 'off' ? cur.judgeModel : model,
+      rejudgeGrowth: num(flags.rejudgeGrowth, cur.rejudgeGrowth),
+      topN: num(flags.topN, cur.topN),
+      minPrompts: num(flags.minPrompts, cur.minPrompts),
+      minToolCalls: num(flags.minToolCalls, cur.minToolCalls),
+      redactEmails: flags.redactEmails === undefined ? cur.redactEmails : flags.redactEmails !== 'false',
+      redactTerms: flags.redactTerms === undefined ? cur.redactTerms : String(flags.redactTerms === true ? '' : flags.redactTerms).split(',').map((x) => x.trim()).filter(Boolean),
+    };
+    const retention = flags.retention && flags.retention !== 'keep' ? Number(flags.retention) : null;
+    applySetup({ cfg, retention, hook: flags.hook === 'yes' });
+    scan();
+    return;
+  }
+
+  if (cmd === 'uninstall') {
+    // Removes the rating hook and the app copy; your scores stay in ~/.sessionboard unless --purge.
+    const settings = readJSON(CLAUDE_SETTINGS, null);
+    if (settings && hasOurHook(settings)) {
+      patchClaudeSettings((st) => {
+        const kept = st.hooks.SessionEnd.filter((h) => !JSON.stringify(h).includes('sessionboard'));
+        if (kept.length) st.hooks.SessionEnd = kept; else delete st.hooks.SessionEnd;
+        if (!Object.keys(st.hooks).length) delete st.hooks;
+      });
+      console.log(`Removed the sessionboard hook from ${tildify(CLAUDE_SETTINGS)}.`);
+    }
+    fs.rmSync(flags.purge ? DATA_DIR : APP_DIR, { recursive: true, force: true });
+    return console.log(flags.purge ? `Deleted ${tildify(DATA_DIR)}.` : `Your scores are kept in ${tildify(DATA_DIR)} (use --purge to delete them).`);
+  }
+
   if (cmd === 'help' || flags.help || flags.h) return console.log(HELP);
   if (cmd === 'init') return init(flags);
   if (cmd === 'dashboard' || cmd === 'ui') { scan(); return dashboard(flags); }
@@ -976,13 +1064,13 @@ async function main() {
 
   if (cmd === 'update') {
     if (canJudge) await judgePending({ log });
-    else if (!cfg.initialized) log('Not initialized yet; run `sessionboard init` to enable AI rating.\n');
+    else if (!cfg.initialized) log('Not set up yet; run `sessionboard init` (or /sessionboard:setup in Claude Code) to enable AI rating.\n');
     if (!flags.quiet) console.log(`Updated. ${Object.keys(readIndex().sessions).length} sessions indexed → ${tildify(TOP_FILE)}`);
     return;
   }
 
   if (cmd === 'top' || cmd === 'ls') {
-    if (!cfg.initialized) console.log(`\n  ${yellow('!')} AI rating is off until you run ${accent('sessionboard init')}`);
+    if (!cfg.initialized) console.log(`\n  ${yellow('!')} AI rating is off until you run ${accent('sessionboard init')} ${dim('(or /sessionboard:setup in Claude Code)')}`);
     console.log(`\n  ${bold(`Your top ${Number(flags.n) || cfg.topN} agent sessions`)}\n`);
     printTop(readIndex(), Number(flags.n) || cfg.topN);
     console.log(`\n  ${dim('share one:')} ${accent('sessionboard share 1 --html')}   ${dim('dashboard:')} ${accent('sessionboard dashboard')}\n`);

package/commands/setup.md

@@ -0,0 +1,32 @@
+---
+description: Set up sessionboard - choose the judge model and settings, then rate your sessions
+allowed-tools: Bash(node:*), AskUserQuestion
+---
+Current state:
+!`node "${CLAUDE_PLUGIN_ROOT}/bin/sessionboard.mjs" setup-info`
+
+Walk the user through setup. Briefly explain first, in 2-3 lines: when a session ends, a background hook gives it one AI rating (0-10, with a summary and the reason), the best sessions make their board, and any session can be exported as a redacted page to share.
+
+Then ask with AskUserQuestion, preselecting the user's current values where the state above shows them (otherwise put the recommended option first):
+
+Call 1 (four questions):
+1. "Which model should judge your sessions?" - Haiku (Recommended: fast, cheapest) / Sonnet (sharper, ~3x cost) / Opus (best, slowest) / Off (free heuristic only)
+2. "When should a resumed session be re-rated?" - When it grows 25% (Recommended) / When it doubles / Never
+3. "How big is your board?" - Top 3 (Recommended) / Top 5 / Top 10
+4. "Which sessions count?" - Standard: 2+ prompts and 5+ tool calls (Recommended) / Strict: 5+ prompts and 20+ tool calls / Everything
+
+Call 2 (ask only the questions that apply):
+5. Only if cleanupPeriodDays is under 365: "Claude Code deletes transcripts older than N days, so older sessions drop off your board. Keep them longer? This edits ~/.claude/settings.json." - Keep for 10 years (Recommended) / Keep for 1 year / Leave as is
+6. Only if hookInstalled is false: "Rate sessions automatically when they end? This adds one hook to ~/.claude/settings.json." - Yes (Recommended) / No, I'll refresh myself
+7. "Words to hide in exports, like company, product, client or internal host names?" - None / Type them (via Other, comma-separated)
+8. "Redact email addresses in exports?" - Yes (Recommended) / No
+
+Then apply exactly what they chose. Only pass --retention and --hook=yes if they explicitly picked those options:
+
+`node "${CLAUDE_PLUGIN_ROOT}/bin/sessionboard.mjs" setup-apply --judgeModel=<haiku|sonnet|opus|off> --rejudgeGrowth=<1.25|2|0> --topN=<3|5|10> --minPrompts=<2|5|1> --minToolCalls=<5|20|1> --redactEmails=<true|false> --redactTerms="<comma,separated or empty>" --retention=<3650|365|keep> --hook=<yes|no>`
+
+If the judge is on and there are unrated sessions, rate them (one call per session, roughly 8 seconds each; tell the user it's running):
+
+`node "${CLAUDE_PLUGIN_ROOT}/bin/sessionboard.mjs" update`
+
+Finish by running `node "${CLAUDE_PLUGIN_ROOT}/bin/sessionboard.mjs" top` and showing the board as-is, then mention /sessionboard:dashboard and /sessionboard:share 1.

package/commands/top.md

@@ -4,4 +4,4 @@ allowed-tools: Bash(node:*)
 ---
 !`node "${CLAUDE_PLUGIN_ROOT}/bin/sessionboard.mjs" top`
 
-Show the leaderboard above to the user as-is. If it says AI rating is off, tell them to run `node "${CLAUDE_PLUGIN_ROOT}/bin/sessionboard.mjs" init` in a terminal (it asks a couple of setup questions).
+Show the leaderboard above to the user as-is. If it says AI rating is off, suggest running /sessionboard:setup.

package/hooks/hooks.json

@@ -1,9 +1,9 @@
 {
   "hooks": {
-    "SessionEnd": [
+    "SessionStart": [
       {
         "hooks": [
-          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/sessionboard.mjs\" hook", "timeout": 10 }
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/sessionboard.mjs\" plugin-start", "timeout": 10 }
         ]
       }
     ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sessionboard",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "An AI-judged leaderboard of your Claude Code sessions. Keeps your top 3 current and exports them, redacted, for sharing.",
   "type": "module",
   "bin": {