@stackmemoryai/stackmemory 1.2.0 → 1.2.1

package/scripts/install-claude-hooks-auto.js

@@ -5,6 +5,10 @@
  * This runs as a postinstall script to set up tracing hooks and daemon
  *
  * INTERACTIVE: Asks for user consent before modifying ~/.claude
+ *
+ * Writes to ~/.claude/settings.json (the current Claude Code config format).
+ * Uses CANONICAL_HOOKS from hook-installer when dist is available, otherwise
+ * falls back to an inline definition.
  */
 
 import {
@@ -13,6 +17,8 @@ import {
   copyFileSync,
   readFileSync,
   writeFileSync,
+  renameSync,
+  chmodSync,
 } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
@@ -25,11 +31,144 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 const claudeHooksDir = join(homedir(), '.claude', 'hooks');
-const claudeConfigFile = join(homedir(), '.claude', 'hooks.json');
+const claudeSettingsFile = join(homedir(), '.claude', 'settings.json');
 const templatesDir = join(__dirname, '..', 'templates', 'claude-hooks');
 const stackmemoryBinDir = join(homedir(), '.stackmemory', 'bin');
 const distDir = join(__dirname, '..', 'dist');
 
+// ---------------------------------------------------------------------------
+// Try to import from compiled hook-installer; fall back to inline definitions
+// ---------------------------------------------------------------------------
+
+/** @type {Array<{scriptName: string, eventType: string, matcher?: string, timeout?: number, commandPrefix?: string, required: boolean}>} */
+let CANONICAL_HOOKS;
+let mergeSettingsFn;
+let readSettingsFn;
+let writeSettingsAtomicFn;
+
+try {
+  const mod = await import('../dist/src/utils/hook-installer.js');
+  CANONICAL_HOOKS = mod.CANONICAL_HOOKS;
+  mergeSettingsFn = mod.mergeSettings;
+  readSettingsFn = mod.readSettings;
+  writeSettingsAtomicFn = mod.writeSettingsAtomic;
+} catch {
+  // dist not built yet — use inline fallback
+  CANONICAL_HOOKS = [
+    {
+      scriptName: 'session-rescue.sh',
+      eventType: 'Stop',
+      timeout: 12,
+      required: true,
+    },
+    {
+      scriptName: 'stop-checkpoint.js',
+      eventType: 'Stop',
+      timeout: 5,
+      commandPrefix: 'node',
+      required: true,
+    },
+    {
+      scriptName: 'chime-on-stop.sh',
+      eventType: 'Stop',
+      timeout: 2,
+      required: true,
+    },
+    {
+      scriptName: 'auto-checkpoint.js',
+      eventType: 'PostToolUse',
+      timeout: 2,
+      commandPrefix: 'node',
+      required: true,
+    },
+  ];
+
+  const DEAD_HOOKS = ['sms-response-handler.js'];
+
+  readSettingsFn = (p) => {
+    try {
+      if (existsSync(p)) return JSON.parse(readFileSync(p, 'utf8'));
+    } catch {
+      /* parse error */
+    }
+    return {};
+  };
+
+  writeSettingsAtomicFn = (settings, p) => {
+    const dir = dirname(p);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const tmp = p + '.tmp';
+    writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n');
+    renameSync(tmp, p);
+  };
+
+  mergeSettingsFn = (existing, hooksDir) => {
+    const merged = JSON.parse(JSON.stringify(existing));
+    if (!merged.hooks) merged.hooks = {};
+
+    // Remove dead hooks
+    for (const eventType of Object.keys(merged.hooks)) {
+      const groups = merged.hooks[eventType];
+      for (const group of groups) {
+        group.hooks = group.hooks.filter((h) => {
+          for (const dead of DEAD_HOOKS) {
+            if (h.command.includes(dead)) return false;
+          }
+          return true;
+        });
+      }
+      merged.hooks[eventType] = groups.filter((g) => g.hooks.length > 0);
+      if (merged.hooks[eventType].length === 0) delete merged.hooks[eventType];
+    }
+
+    // Add missing canonical hooks
+    for (const entry of CANONICAL_HOOKS) {
+      const exists = (merged.hooks[entry.eventType] || []).some((group) =>
+        group.hooks.some((h) => h.command.includes(entry.scriptName))
+      );
+      if (exists) continue;
+
+      const scriptPath = join(hooksDir, entry.scriptName);
+      const command = entry.commandPrefix
+        ? `${entry.commandPrefix} ${scriptPath}`
+        : scriptPath;
+      const hookCmd = { type: 'command', command };
+      if (entry.timeout) hookCmd.timeout = entry.timeout;
+
+      const eventGroups = merged.hooks[entry.eventType] || [];
+      const matcherValue = entry.matcher;
+      let targetGroup = eventGroups.find((g) =>
+        matcherValue ? g.matcher === matcherValue : !g.matcher
+      );
+
+      if (targetGroup) {
+        targetGroup.hooks.push(hookCmd);
+      } else {
+        const newGroup = { hooks: [hookCmd] };
+        if (matcherValue) newGroup.matcher = matcherValue;
+        eventGroups.push(newGroup);
+      }
+      merged.hooks[entry.eventType] = eventGroups;
+    }
+
+    return merged;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Legacy hook files (still installed for backward-compat tooling hooks)
+// ---------------------------------------------------------------------------
+
+const LEGACY_HOOK_FILES = [
+  'tool-use-trace.js',
+  'on-startup.js',
+  'on-clear.js',
+  'on-task-complete.js',
+  'skill-eval.sh',
+  'skill-eval.cjs',
+];
+const LEGACY_DATA_FILES = ['skill-rules.json'];
+
 /**
  * Ask user for confirmation before installing hooks
  * Returns true if user consents, false otherwise
@@ -51,14 +190,13 @@ async function askForConsent() {
     return false;
   }
 
-  console.log('\n📦 StackMemory Post-Install\n');
+  console.log('\nStackMemory Post-Install\n');
   console.log(
     'StackMemory can integrate with Claude Code by installing hooks that:'
   );
   console.log('  - Track tool usage for better context');
   console.log('  - Enable session persistence across restarts');
-  console.log('  - Sync context with Linear (optional)');
-  console.log('  - Auto-update PROMPT_PLAN on task completion');
+  console.log('  - Auto-checkpoint and session rescue');
   console.log('  - Recommend relevant skills based on your prompts');
   console.log('\nThis will modify files in ~/.claude/\n');
 
@@ -91,24 +229,38 @@ async function installClaudeHooks() {
       console.log('Created ~/.claude/hooks directory');
     }
 
-    // Copy hook files (scripts + data files)
-    const hookFiles = [
-      'tool-use-trace.js',
-      'on-startup.js',
-      'on-clear.js',
-      'on-task-complete.js',
-      'skill-eval.sh',
-      'skill-eval.cjs',
-    ];
-    const dataFiles = ['skill-rules.json'];
     let installed = 0;
 
-    for (const hookFile of [...hookFiles, ...dataFiles]) {
+    // --- Install canonical session-persistence hooks ---
+    for (const entry of CANONICAL_HOOKS) {
+      const srcPath = join(templatesDir, entry.scriptName);
+      const destPath = join(claudeHooksDir, entry.scriptName);
+
+      if (existsSync(srcPath)) {
+        // Backup existing hook if it exists
+        if (existsSync(destPath)) {
+          const backupPath = `${destPath}.backup-${Date.now()}`;
+          copyFileSync(destPath, backupPath);
+          console.log(`  Backed up: ${entry.scriptName}`);
+        }
+
+        copyFileSync(srcPath, destPath);
+        try {
+          chmodSync(destPath, 0o755);
+        } catch {
+          // Silent fail on chmod
+        }
+        installed++;
+        console.log(`  Installed: ${entry.scriptName}`);
+      }
+    }
+
+    // --- Install legacy tooling hooks ---
+    for (const hookFile of [...LEGACY_HOOK_FILES, ...LEGACY_DATA_FILES]) {
       const srcPath = join(templatesDir, hookFile);
       const destPath = join(claudeHooksDir, hookFile);
 
       if (existsSync(srcPath)) {
-        // Backup existing hook if it exists
         if (existsSync(destPath)) {
           const backupPath = `${destPath}.backup-${Date.now()}`;
           copyFileSync(destPath, backupPath);
@@ -117,11 +269,9 @@ async function installClaudeHooks() {
 
         copyFileSync(srcPath, destPath);
 
-        // Make executable (scripts only, not data files)
-        if (!dataFiles.includes(hookFile)) {
+        if (!LEGACY_DATA_FILES.includes(hookFile)) {
           try {
-            const { execSync } = await import('child_process');
-            execSync(`chmod +x "${destPath}"`, { stdio: 'ignore' });
+            chmodSync(destPath, 0o755);
           } catch {
             // Silent fail on chmod
           }
@@ -132,30 +282,14 @@ async function installClaudeHooks() {
       }
     }
 
-    // Update hooks.json configuration
-    let hooksConfig = {};
-    if (existsSync(claudeConfigFile)) {
-      try {
-        hooksConfig = JSON.parse(readFileSync(claudeConfigFile, 'utf8'));
-      } catch {
-        // Start fresh if parse fails
-      }
-    }
-
-    // Add our hooks (don't overwrite existing hooks unless they're ours)
-    const newHooksConfig = {
-      ...hooksConfig,
-      'tool-use-approval': join(claudeHooksDir, 'tool-use-trace.js'),
-      'on-startup': join(claudeHooksDir, 'on-startup.js'),
-      'on-clear': join(claudeHooksDir, 'on-clear.js'),
-      'on-task-complete': join(claudeHooksDir, 'on-task-complete.js'),
-      'user-prompt-submit': join(claudeHooksDir, 'skill-eval.sh'),
-    };
-
-    writeFileSync(claudeConfigFile, JSON.stringify(newHooksConfig, null, 2));
+    // --- Update settings.json (not the deprecated hooks.json) ---
+    const currentSettings = readSettingsFn(claudeSettingsFile);
+    const merged = mergeSettingsFn(currentSettings, claudeHooksDir);
+    writeSettingsAtomicFn(merged, claudeSettingsFile);
 
     if (installed > 0) {
       console.log(`\n[OK] Installed ${installed} Claude hooks`);
+      console.log(`     Config: ~/.claude/settings.json`);
       console.log(`     Traces: ~/.stackmemory/traces/`);
       console.log('     To disable: set DEBUG_TRACE=false in .env');
     }
@@ -189,10 +323,8 @@ async function installSessionDaemon() {
     if (existsSync(daemonSrc)) {
       copyFileSync(daemonSrc, daemonDest);
 
-      // Make executable
       try {
-        const { execSync } = await import('child_process');
-        execSync(`chmod +x "${daemonDest}"`, { stdio: 'ignore' });
+        chmodSync(daemonDest, 0o755);
       } catch {
         // Silent fail on chmod
       }

package/templates/claude-hooks/auto-checkpoint.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+/**
+ * Auto-Checkpoint Hook (PostToolUse)
+ *
+ * Counts tool calls per project session. Every 25 calls, writes a lightweight
+ * checkpoint to ~/.stackmemory/checkpoints/{project-hash}/latest.json.
+ * Must complete in <50ms -- pure file I/O only.
+ *
+ * State is keyed per-session (process.ppid) to avoid race conditions
+ * when multiple Claude instances run concurrently.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const CHECKPOINT_INTERVAL = 25;
+const SAVE_INTERVAL = 5;
+const MAX_RECENT_TOOLS = 20;
+const MAX_FILES_TRACKED = 50;
+const TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+const HOME = process.env.HOME || '/tmp';
+const SESSION_ID = process.env.CLAUDE_INSTANCE_ID || String(process.ppid);
+const STATE_FILE = path.join(
+  HOME,
+  '.stackmemory',
+  `checkpoint-state-${SESSION_ID}.json`
+);
+
+function projectHash(cwd) {
+  return crypto.createHash('md5').update(cwd).digest('hex').slice(0, 12);
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function safeWriteFile(filePath, content) {
+  const tmp = filePath + '.tmp';
+  fs.writeFileSync(tmp, content);
+  fs.renameSync(tmp, filePath);
+}
+
+function loadState() {
+  try {
+    if (fs.existsSync(STATE_FILE)) {
+      const state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf-8'));
+      const cutoff = Date.now() - TTL_MS;
+      for (const [cwd, proj] of Object.entries(state.projects)) {
+        if (
+          proj.sessionStart &&
+          new Date(proj.sessionStart).getTime() < cutoff
+        ) {
+          delete state.projects[cwd];
+        }
+      }
+      return state;
+    }
+  } catch {
+    // Corrupted state, start fresh
+  }
+  return { projects: {} };
+}
+
+function saveState(state) {
+  try {
+    ensureDir(path.dirname(STATE_FILE));
+    safeWriteFile(STATE_FILE, JSON.stringify(state));
+  } catch {
+    // Best-effort
+  }
+}
+
+function getProjectState(state, cwd) {
+  if (!state.projects[cwd]) {
+    state.projects[cwd] = {
+      toolCount: 0,
+      checkpointCount: 0,
+      lastCheckpoint: null,
+      sessionStart: new Date().toISOString(),
+      filesModified: [],
+      recentTools: [],
+    };
+  }
+  return state.projects[cwd];
+}
+
+function writeCheckpoint(proj, cwd) {
+  const hash = projectHash(cwd);
+  const cpDir = path.join(HOME, '.stackmemory', 'checkpoints', hash);
+  ensureDir(cpDir);
+
+  const checkpoint = {
+    toolCount: proj.toolCount,
+    checkpointNumber: proj.checkpointCount,
+    timestamp: new Date().toISOString(),
+    filesModified: proj.filesModified.slice(-MAX_FILES_TRACKED),
+    recentTools: proj.recentTools.slice(-MAX_RECENT_TOOLS),
+    cwd,
+  };
+
+  safeWriteFile(
+    path.join(cpDir, 'latest.json'),
+    JSON.stringify(checkpoint, null, 2)
+  );
+}
+
+function trackFile(proj, toolInput) {
+  const filePath = toolInput?.file_path;
+  if (filePath && !proj.filesModified.includes(filePath)) {
+    proj.filesModified.push(filePath);
+    if (proj.filesModified.length > MAX_FILES_TRACKED) {
+      proj.filesModified = proj.filesModified.slice(-MAX_FILES_TRACKED);
+    }
+  }
+}
+
+async function readInput() {
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+  return JSON.parse(input);
+}
+
+async function main() {
+  try {
+    const input = await readInput();
+    const { tool_name, tool_input } = input;
+
+    const cwd = process.cwd();
+    const state = loadState();
+    const proj = getProjectState(state, cwd);
+
+    // Increment counter
+    proj.toolCount++;
+
+    // Track tool name
+    proj.recentTools.push(tool_name);
+    if (proj.recentTools.length > MAX_RECENT_TOOLS) {
+      proj.recentTools = proj.recentTools.slice(-MAX_RECENT_TOOLS);
+    }
+
+    // Track modified files from Edit/Write
+    if (
+      tool_name === 'Edit' ||
+      tool_name === 'Write' ||
+      tool_name === 'MultiEdit'
+    ) {
+      trackFile(proj, tool_input);
+    }
+
+    // Checkpoint every N calls
+    const isCheckpoint = proj.toolCount % CHECKPOINT_INTERVAL === 0;
+    if (isCheckpoint) {
+      proj.checkpointCount++;
+      proj.lastCheckpoint = new Date().toISOString();
+      writeCheckpoint(proj, cwd);
+    }
+
+    // Only persist state every SAVE_INTERVAL calls or on checkpoint boundaries
+    if (isCheckpoint || proj.toolCount % SAVE_INTERVAL === 0) {
+      saveState(state);
+    }
+  } catch {
+    // Silent fail -- never block the agent
+  }
+}
+
+main();

package/templates/claude-hooks/chime-on-stop.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Chime once when Claude Code needs user input
+# Uses macOS system sound
+
+# Prevent multiple chimes by checking if we recently played
+CHIME_LOCK="/tmp/claude-chime-lock"
+CHIME_COOLDOWN=2  # seconds
+
+if [ -f "$CHIME_LOCK" ]; then
+  LAST_CHIME=$(cat "$CHIME_LOCK")
+  NOW=$(date +%s)
+  DIFF=$((NOW - LAST_CHIME))
+  if [ "$DIFF" -lt "$CHIME_COOLDOWN" ]; then
+    exit 0  # Skip chime if too recent
+  fi
+fi
+
+# Record chime time
+date +%s > "$CHIME_LOCK"
+
+# Play system sound (Glass is a nice subtle chime)
+afplay /System/Library/Sounds/Glass.aiff &

package/templates/claude-hooks/session-rescue.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# session-rescue.sh — Auto-capture stackmemory handoff on session close
+# Runs as a Stop hook. Silent on failure. Skips non-stackmemory projects.
+
+set -euo pipefail
+
+# Only run in stackmemory-initialized projects
+[ -d ".stackmemory" ] || exit 0
+
+# Require stackmemory CLI
+command -v stackmemory >/dev/null 2>&1 || exit 0
+
+# Capture without committing, compact format, 10s timeout
+timeout 10 stackmemory capture --no-commit --format compact \
+  -m "auto-rescue on session close" >/dev/null 2>&1 || true

package/templates/claude-hooks/stop-checkpoint.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+/**
+ * Stop-Checkpoint Hook
+ *
+ * Fires on session stop. Reads checkpoint state for current project.
+ * If 3+ checkpoints accumulated, outputs a "context heavy" message.
+ * Writes a final checkpoint with session stop metadata.
+ *
+ * State is keyed per-session (process.ppid) to avoid race conditions
+ * when multiple Claude instances run concurrently.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const HOME = process.env.HOME || '/tmp';
+const SESSION_ID = process.env.CLAUDE_INSTANCE_ID || String(process.ppid);
+const STATE_FILE = path.join(
+  HOME,
+  '.stackmemory',
+  `checkpoint-state-${SESSION_ID}.json`
+);
+const MAX_FILES_TRACKED = 50;
+const MAX_RECENT_TOOLS = 20;
+
+function projectHash(cwd) {
+  return crypto.createHash('md5').update(cwd).digest('hex').slice(0, 12);
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function safeWriteFile(filePath, content) {
+  const tmp = filePath + '.tmp';
+  fs.writeFileSync(tmp, content);
+  fs.renameSync(tmp, filePath);
+}
+
+function loadState() {
+  try {
+    if (fs.existsSync(STATE_FILE)) {
+      const state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf-8'));
+      const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+      for (const [cwd, proj] of Object.entries(state.projects)) {
+        if (
+          proj.sessionStart &&
+          new Date(proj.sessionStart).getTime() < cutoff
+        ) {
+          delete state.projects[cwd];
+        }
+      }
+      return state;
+    }
+  } catch {
+    // Corrupted state, start fresh
+  }
+  return { projects: {} };
+}
+
+function main() {
+  try {
+    const cwd = process.cwd();
+    const state = loadState();
+    const proj = state.projects?.[cwd];
+
+    if (!proj) return;
+
+    const { toolCount, checkpointCount, sessionStart, filesModified } = proj;
+
+    // Write final checkpoint
+    const hash = projectHash(cwd);
+    const cpDir = path.join(HOME, '.stackmemory', 'checkpoints', hash);
+    ensureDir(cpDir);
+
+    // NaN duration guard
+    const startMs = sessionStart ? new Date(sessionStart).getTime() : 0;
+    const duration =
+      startMs > 0 ? Math.round((Date.now() - startMs) / 1000) : 0;
+
+    const finalCheckpoint = {
+      reason: 'session_stop',
+      toolCount,
+      checkpointNumber: checkpointCount,
+      totalFiles: filesModified?.length || 0,
+      duration,
+      timestamp: new Date().toISOString(),
+      filesModified: (filesModified || []).slice(-MAX_FILES_TRACKED),
+      recentTools: (proj.recentTools || []).slice(-MAX_RECENT_TOOLS),
+      cwd,
+    };
+
+    safeWriteFile(
+      path.join(cpDir, 'latest.json'),
+      JSON.stringify(finalCheckpoint, null, 2)
+    );
+
+    // Output context-heavy message if 3+ checkpoints
+    if (checkpointCount >= 3) {
+      console.error(
+        `\nContext heavy (${checkpointCount} checkpoints, ${toolCount} tool calls). State saved. Consider /clear to reload from checkpoint.\n`
+      );
+    }
+
+    // Clean up session state file since session is ending
+    try {
+      fs.unlinkSync(STATE_FILE);
+    } catch {
+      // Best-effort cleanup
+    }
+  } catch {
+    // Silent fail -- never block the agent
+  }
+}
+
+main();