@claudemini/ses-cli 1.4.3

package/lib/explain.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+/**
+ * Explain a session or checkpoint
+ * Provides human-readable explanation of what happened in a session
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { execFileSync } from 'child_process';
+import { getProjectRoot, SESSION_ID_REGEX } from './config.js';
+
+function git(args, cwd, ignoreError = false) {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      encoding: 'utf-8',
+      timeout: 10000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch (error) {
+    if (ignoreError) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+function getSessionData(sessionId, projectRoot) {
+  const sessionDir = join(projectRoot, '.ses-logs', sessionId);
+
+  if (!existsSync(sessionDir)) {
+    return null;
+  }
+
+  const files = {};
+  const fileNames = ['summary.json', 'summary.txt', 'context.md', 'metadata.json'];
+
+  for (const file of fileNames) {
+    const filePath = join(sessionDir, file);
+    if (existsSync(filePath)) {
+      files[file] = readFileSync(filePath, 'utf-8');
+    }
+  }
+
+  return { dir: sessionDir, files };
+}
+
+function explainFromSummary(summaryText) {
+  const explanation = [];
+
+  // Extract key information
+  const typeMatch = summaryText.match(/Type:\s*(\w+)/i);
+  const riskMatch = summaryText.match(/Risk:\s*(\w+)/i);
+  const intentMatch = summaryText.match(/Goal:\s*(.+)/i);
+  const durationMatch = summaryText.match(/Duration:\s*(\d+)min/i);
+
+  if (typeMatch) {
+    explanation.push(`📋 Session type: **${typeMatch[1]}**`);
+  }
+
+  if (riskMatch) {
+    const risk = riskMatch[1].toLowerCase();
+    const emoji = risk === 'high' ? '🔴' : risk === 'medium' ? '🟡' : '🟢';
+    explanation.push(`${emoji} Risk level: **${risk}**`);
+  }
+
+  if (intentMatch) {
+    explanation.push(`🎯 Intent: ${intentMatch[1].slice(0, 100)}`);
+  }
+
+  if (durationMatch) {
+    explanation.push(`⏱️  Duration: ${durationMatch[1]} minutes`);
+  }
+
+  // Extract files changed
+  const changesMatch = summaryText.match(/## Changes\n([\s\S]+?)##/);
+  if (changesMatch) {
+    const fileLines = changesMatch[1].split('\n').filter(l => l.trim().startsWith('['));
+    if (fileLines.length > 0) {
+      explanation.push(`\n📝 Files changed (${fileLines.length}):`);
+      fileLines.slice(0, 5).forEach(line => {
+        explanation.push(`   ${line.trim()}`);
+      });
+      if (fileLines.length > 5) {
+        explanation.push(`   ... and ${fileLines.length - 5} more`);
+      }
+    }
+  }
+
+  // Extract tools used
+  const toolsMatch = summaryText.match(/## Tools\n([\s\S]+?)##/);
+  if (toolsMatch) {
+    const toolLines = toolsMatch[1].split('\n').filter(l => l.includes(':'));
+    if (toolLines.length > 0) {
+      explanation.push(`\n🔧 Tools used:`);
+      toolLines.slice(0, 5).forEach(line => {
+        explanation.push(`   ${line.trim()}`);
+      });
+    }
+  }
+
+  // Extract errors
+  if (summaryText.includes('## Errors')) {
+    const errorsMatch = summaryText.match(/## Errors\n([\s\S]+)/);
+    if (errorsMatch && errorsMatch[1].trim()) {
+      explanation.push(`\n⚠️  Errors encountered:`);
+      const errorLines = errorsMatch[1].split('\n').filter(l => l.trim());
+      errorLines.slice(0, 3).forEach(line => {
+        explanation.push(`   ${line.trim()}`);
+      });
+    }
+  }
+
+  return explanation.join('\n');
+}
+
+function explainFromCommit(commitSha, projectRoot) {
+  try {
+    // Try to find associated checkpoint
+    const checkpoints = (git(['branch', '--list', 'ses/checkpoints/v1/*'], projectRoot, true) || '')
+      .split('\n')
+      .map(line => line.trim().replace(/^\*?\s*/, ''))
+      .filter(Boolean);
+
+    for (const branch of checkpoints) {
+      try {
+        const log = git(['log', branch, '--oneline', '-1'], projectRoot, true);
+        if (!log) {
+          continue;
+        }
+
+        if (log.includes(commitSha.slice(0, 12))) {
+          const message = git(['log', branch, '--format=%B', '-1'], projectRoot, true) || '';
+
+          return `📸 This commit has an associated checkpoint:\n\nBranch: ${branch}\n\n${message}`;
+        }
+      } catch {
+        // Skip this branch
+      }
+    }
+
+    return `No checkpoint found for commit ${commitSha}`;
+  } catch {
+    return 'No checkpoint information available';
+  }
+}
+
+export default async function explain(args) {
+  try {
+    const projectRoot = getProjectRoot();
+    const target = args[0];
+
+    if (!target) {
+      console.log('Usage: ses explain <session-id | commit-sha>');
+      console.log('\nExamples:');
+      console.log('  ses explain b5613b31-c732-4546-9be5-f8ae36f2327f  # Explain a session');
+      console.log('  ses explain abc1234              # Explain a commit');
+      process.exit(1);
+    }
+
+    console.log(`🔍 Explaining: ${target}\n`);
+
+    // Try to find session first
+    const sessionData = getSessionData(target, projectRoot);
+
+    if (sessionData && sessionData.files['summary.txt']) {
+      console.log('📋 Session Explanation\n');
+      console.log(explainFromSummary(sessionData.files['summary.txt']));
+      console.log('\n---\n💡 Use "ses view ' + target + '" for full details');
+      return;
+    }
+
+    // Try as commit
+    const isCommitLike = /^[a-f0-9]{4,40}$/i.test(target);
+    if (isCommitLike) {
+      const resolvedCommit = git(['rev-parse', '--verify', `${target}^{commit}`], projectRoot, true);
+      if (resolvedCommit) {
+        console.log('📸 Commit Explanation\n');
+        console.log(explainFromCommit(resolvedCommit, projectRoot));
+        return;
+      }
+    }
+
+    // Not a commit
+
+    // Try partial match
+    const logDir = join(projectRoot, '.ses-logs');
+    const sessions = existsSync(logDir)
+      ? readdirSync(logDir, { withFileTypes: true })
+        .filter(entry => entry.isDirectory() && SESSION_ID_REGEX.test(entry.name))
+        .map(entry => entry.name)
+        .filter(name => name.includes(target))
+      : [];
+
+    if (sessions.length > 0) {
+      const matchedSession = sessions[0];
+      const data = getSessionData(matchedSession, projectRoot);
+      if (data && data.files['summary.txt']) {
+        console.log('📋 Found session: ' + matchedSession + '\n');
+        console.log(explainFromSummary(data.files['summary.txt']));
+        return;
+      }
+    }
+
+    console.log(`❌ Could not find session or commit: ${target}`);
+
+  } catch (error) {
+    console.error('❌ Failed to explain:', error.message);
+    process.exit(1);
+  }
+}

package/lib/extract.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+
+/**
+ * Semantic extraction engine.
+ * Transforms raw hook events into structured, meaningful data
+ * for both humans and code review bots.
+ */
+
+// --- Intent extraction from user prompts ---
+
+const INTENT_PATTERNS = [
+  { pattern: /\b(fix|bug|error|crash|broken|issue|wrong|fail)\b/i, type: 'bugfix' },
+  { pattern: /\b(add|create|implement|new|feature|introduce)\b/i, type: 'feature' },
+  { pattern: /\b(refactor|clean|reorganize|restructure|extract|move|rename|simplify)\b/i, type: 'refactor' },
+  { pattern: /\b(debug|investigate|trace|log|print|inspect|check)\b/i, type: 'debug' },
+  { pattern: /\b(test|spec|coverage|assert)\b/i, type: 'test' },
+  { pattern: /\b(doc|readme|comment|explain|document)\b/i, type: 'docs' },
+  { pattern: /\b(deploy|release|publish|build|ci|cd|pipeline)\b/i, type: 'devops' },
+  { pattern: /\b(upgrade|update|bump|migrate|version)\b/i, type: 'upgrade' },
+  { pattern: /\b(config|setting|env|environment|setup)\b/i, type: 'config' },
+  { pattern: /\b(style|format|lint|prettier|css|ui|layout)\b/i, type: 'style' },
+  { pattern: /\b(security|auth|permission|token|secret|vulnerability)\b/i, type: 'security' },
+  { pattern: /\b(perf|performance|optimize|speed|slow|fast|cache)\b/i, type: 'perf' },
+];
+
+const SCOPE_PATTERNS = [
+  { pattern: /\b(auth|login|token|jwt|session|password)\b/i, scope: 'auth' },
+  { pattern: /\b(api|endpoint|route|controller|handler)\b/i, scope: 'api' },
+  { pattern: /\b(database|db|prisma|migration|schema|sql|query)\b/i, scope: 'database' },
+  { pattern: /\b(test|spec|jest|vitest)\b/i, scope: 'testing' },
+  { pattern: /\b(ui|component|page|view|template|frontend)\b/i, scope: 'ui' },
+  { pattern: /\b(deploy|docker|ci|pipeline|k8s|server)\b/i, scope: 'infra' },
+  { pattern: /\b(config|env|setting)\b/i, scope: 'config' },
+  { pattern: /\b(webhook|hook|event)\b/i, scope: 'webhook' },
+  { pattern: /\b(agent|bot|worker)\b/i, scope: 'agent' },
+  { pattern: /\b(job|task|queue)\b/i, scope: 'job' },
+];
+
+export function extractIntent(prompts) {
+  if (!prompts || prompts.length === 0) {
+    return { goal: '', type: 'unknown', scope: [] };
+  }
+
+  // Use all prompts for classification, but first prompt is typically the main goal
+  const allText = prompts.map(p => typeof p === 'string' ? p : p.text || '').join(' ');
+  const firstPrompt = typeof prompts[0] === 'string' ? prompts[0] : prompts[0].text || '';
+
+  // Determine type by counting pattern matches across all prompts
+  const typeCounts = {};
+  for (const { pattern, type } of INTENT_PATTERNS) {
+    const matches = allText.match(new RegExp(pattern, 'gi'));
+    if (matches) typeCounts[type] = (typeCounts[type] || 0) + matches.length;
+  }
+
+  const type = Object.entries(typeCounts)
+    .sort((a, b) => b[1] - a[1])[0]?.[0] || 'unknown';
+
+  // Extract scopes
+  const scopes = new Set();
+  for (const { pattern, scope } of SCOPE_PATTERNS) {
+    if (pattern.test(allText)) scopes.add(scope);
+  }
+
+  // Goal: use first prompt, truncated
+  const goal = firstPrompt.slice(0, 200).trim();
+
+  return { goal, type, scope: [...scopes] };
+}
+
+// --- Change extraction from tool events ---
+
+const FILE_CATEGORIES = [
+  { pattern: /\.(spec|test)\.(ts|js|tsx|jsx)$/, category: 'test' },
+  { pattern: /__(tests|mocks|fixtures)__\//, category: 'test' },
+  { pattern: /\.(config|rc)\.(ts|js|json|yaml|yml)$/, category: 'config' },
+  { pattern: /\.(env|env\.\w+)$/, category: 'config' },
+  { pattern: /\.gitignore|\.eslintrc|\.prettierrc|tsconfig/, category: 'config' },
+  { pattern: /prisma\/.*\.prisma$/, category: 'config' },
+  { pattern: /prisma\/migrations\//, category: 'migration' },
+  { pattern: /\.(md|txt|rst|doc)$/, category: 'doc' },
+  { pattern: /README|CHANGELOG|LICENSE|CONTRIBUTING/, category: 'doc' },
+  { pattern: /scripts\/|\.sh$/, category: 'script' },
+  { pattern: /Dockerfile|docker-compose|\.dockerignore/, category: 'infra' },
+  { pattern: /\.github\/|\.gitlab-ci|\.circleci/, category: 'infra' },
+  { pattern: /package(-lock)?\.json|yarn\.lock|pnpm-lock/, category: 'deps' },
+];
+
+function categorizeFile(filePath) {
+  for (const { pattern, category } of FILE_CATEGORIES) {
+    if (pattern.test(filePath)) return category;
+  }
+  return 'source';
+}
+
+const COMMAND_CATEGORIES = [
+  { pattern: /\b(test|jest|vitest|mocha|cypress|playwright)\b/i, category: 'test' },
+  { pattern: /\b(build|compile|tsc|webpack|vite|rollup|esbuild)\b/i, category: 'build' },
+  { pattern: /\bgit\b/i, category: 'git' },
+  { pattern: /\b(deploy|ssh|scp|rsync|docker)\b/i, category: 'deploy' },
+  { pattern: /\b(npm|yarn|pnpm|pip|cargo)\s+(install|add|remove)/i, category: 'install' },
+  { pattern: /\b(lint|eslint|prettier|format)\b/i, category: 'lint' },
+  { pattern: /\b(prisma|migrate|migration)\b/i, category: 'database' },
+];
+
+function categorizeCommand(cmd) {
+  for (const { pattern, category } of COMMAND_CATEGORIES) {
+    if (pattern.test(cmd)) return category;
+  }
+  return 'other';
+}
+
+export function extractChanges(state) {
+  const fileMap = new Map(); // path -> entry
+
+  // Process file operations
+  for (const path of (state.file_ops?.write || [])) {
+    const entry = getOrCreateFile(fileMap, path);
+    if (!entry.operations.includes('write')) entry.operations.push('write');
+  }
+  for (const path of (state.file_ops?.edit || [])) {
+    const entry = getOrCreateFile(fileMap, path);
+    if (!entry.operations.includes('edit')) entry.operations.push('edit');
+  }
+  for (const path of (state.file_ops?.read || [])) {
+    const entry = getOrCreateFile(fileMap, path);
+    if (!entry.operations.includes('read')) entry.operations.push('read');
+  }
+
+  // Enrich with edit counts and summaries
+  for (const edit of (state.edits || [])) {
+    const entry = fileMap.get(edit.file);
+    if (entry) {
+      entry.editCount = (entry.editCount || 0) + 1;
+      if (edit.new && !entry.editSummary) {
+        entry.editSummary = edit.new.slice(0, 100);
+      }
+    }
+  }
+
+  // Categorize commands
+  const commands = {};
+  for (const cmd of (state.commands || [])) {
+    const cat = categorizeCommand(cmd);
+    if (!commands[cat]) commands[cat] = [];
+    commands[cat].push(cmd);
+  }
+
+  // Build summary counts (modified files only)
+  const summary = {};
+  for (const [, entry] of fileMap) {
+    if (entry.operations.some(op => op !== 'read')) {
+      summary[entry.category] = (summary[entry.category] || 0) + 1;
+    }
+  }
+
+  return {
+    files: [...fileMap.values()],
+    commands,
+    summary,
+  };
+}
+
+function getOrCreateFile(fileMap, path) {
+  if (!fileMap.has(path)) {
+    fileMap.set(path, {
+      path,
+      category: categorizeFile(path),
+      operations: [],
+      editCount: 0,
+      editSummary: '',
+    });
+  }
+  return fileMap.get(path);
+}
+
+// --- Session classification ---
+
+export function classifySession(intent, changes) {
+  const type = intent.type !== 'unknown' ? intent.type : inferTypeFromChanges(changes);
+
+  const risk = assessRisk(changes);
+
+  const testsRun = !!(changes.commands?.test?.length > 0);
+  const buildVerified = !!(changes.commands?.build?.length > 0);
+
+  // Find source files that lack corresponding test files
+  const sourceFiles = changes.files
+    .filter(f => f.category === 'source' && f.operations.some(op => op !== 'read'));
+  const testFiles = new Set(
+    changes.files.filter(f => f.category === 'test').map(f => f.path)
+  );
+  const filesWithoutTests = sourceFiles
+    .filter(f => {
+      const testVariants = [
+        f.path.replace(/\.(ts|js)$/, '.spec.$1'),
+        f.path.replace(/\.(ts|js)$/, '.test.$1'),
+        f.path.replace(/src\//, 'test/').replace(/\.(ts|js)$/, '.e2e-spec.$1'),
+      ];
+      return !testVariants.some(tv => testFiles.has(tv));
+    })
+    .map(f => f.path);
+
+  const modifiedFileCount = changes.files
+    .filter(f => f.operations.some(op => op !== 'read')).length;
+
+  const summary = buildSummary(intent, type, modifiedFileCount);
+
+  return {
+    type,
+    risk,
+    summary,
+    reviewHints: {
+      testsRun,
+      buildVerified,
+      filesWithoutTests,
+      largeChange: modifiedFileCount > 10,
+      configChanged: changes.files.some(f => f.category === 'config' && f.operations.some(op => op !== 'read')),
+      migrationAdded: changes.files.some(f => f.category === 'migration' && f.operations.some(op => op !== 'read')),
+    },
+  };
+}
+
+function inferTypeFromChanges(changes) {
+  if (changes.files.some(f => f.category === 'test' && f.operations.includes('write'))) return 'test';
+  if (changes.files.some(f => f.category === 'doc' && f.operations.some(op => op !== 'read'))) return 'docs';
+  if (changes.files.some(f => f.category === 'config' && f.operations.some(op => op !== 'read'))) return 'config';
+  if (changes.files.some(f => f.category === 'infra' && f.operations.some(op => op !== 'read'))) return 'devops';
+  return 'unknown';
+}
+
+function assessRisk(changes) {
+  let score = 0;
+  const modified = changes.files.filter(f => f.operations.some(op => op !== 'read'));
+
+  // More files = more risk
+  if (modified.length > 10) score += 2;
+  else if (modified.length > 5) score += 1;
+
+  // Config/migration changes are risky
+  if (modified.some(f => f.category === 'config')) score += 1;
+  if (modified.some(f => f.category === 'migration')) score += 2;
+  if (modified.some(f => f.category === 'infra')) score += 1;
+
+  // Tests reduce risk
+  if (changes.commands?.test?.length > 0) score -= 1;
+
+  if (score >= 3) return 'high';
+  if (score >= 1) return 'medium';
+  return 'low';
+}
+
+function buildSummary(intent, type, fileCount) {
+  const typeLabel = {
+    bugfix: 'Fixed', feature: 'Added', refactor: 'Refactored',
+    debug: 'Debugged', test: 'Tested', docs: 'Documented',
+    devops: 'DevOps', upgrade: 'Upgraded', config: 'Configured',
+    style: 'Styled', security: 'Security fix', perf: 'Optimized',
+    unknown: 'Modified',
+  }[type] || 'Modified';
+
+  if (intent.goal) {
+    return `${typeLabel}: ${intent.goal.slice(0, 150)}`;
+  }
+  return `${typeLabel} ${fileCount} file(s)`;
+}

package/lib/git-shadow.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+
+/**
+ * Shadow branch module - saves session logs to orphan git branches.
+ *
+ * Approach (same as .entire):
+ *   - Creates orphan branches: ses/<base-commit>-<session-short>
+ *   - Uses git plumbing commands (no checkout, no working tree impact)
+ *   - Each session-end/stop creates a commit on the shadow branch
+ *
+ * Branch naming: ses/<HEAD-short>-<session-id-first-8>
+ */
+
+import { readdirSync, readFileSync, statSync } from 'fs';
+import { execSync } from 'child_process';
+import { join, basename } from 'path';
+
+function git(cmd, cwd) {
+  return execSync(`git ${cmd}`, { cwd, encoding: 'utf-8', timeout: 10000 }).trim();
+}
+
+function gitRaw(cmd, cwd, input) {
+  return execSync(`git ${cmd}`, {
+    cwd, encoding: 'utf-8', timeout: 10000,
+    input,
+  }).trim();
+}
+
+/**
+ * Build a git tree from a directory using plumbing commands.
+ * Returns the tree SHA.
+ */
+function buildTree(cwd, dirPath) {
+  const entries = readdirSync(dirPath);
+  const treeLines = [];
+
+  for (const name of entries) {
+    const fullPath = join(dirPath, name);
+    const stat = statSync(fullPath);
+
+    if (stat.isDirectory()) {
+      const subTreeSha = buildTree(cwd, fullPath);
+      treeLines.push(`040000 tree ${subTreeSha}\t${name}`);
+    } else {
+      const content = readFileSync(fullPath);
+      const blobSha = gitRaw('hash-object -w --stdin', cwd, content);
+      treeLines.push(`100644 blob ${blobSha}\t${name}`);
+    }
+  }
+
+  if (treeLines.length === 0) return null;
+  return gitRaw('mktree', cwd, treeLines.join('\n'));
+}
+
+/**
+ * Commit session logs to a shadow branch.
+ * Called on session-end or stop.
+ */
+export async function commitShadow(projectRoot, sessionDir, sessionId) {
+  // Verify we're in a git repo
+  try {
+    git('rev-parse --git-dir', projectRoot);
+  } catch {
+    return; // not a git repo, skip
+  }
+
+  const headShort = git('rev-parse --short HEAD', projectRoot);
+  const sessionShort = sessionId.slice(0, 8);
+  const branchName = `ses/${headShort}-${sessionShort}`;
+  const refPath = `refs/heads/${branchName}`;
+
+  // Build tree from session directory
+  const sessionTree = buildTree(projectRoot, sessionDir);
+  if (!sessionTree) return;
+
+  // Wrap session files under .ses-logs/<session-id>/ in the tree
+  const wrapperLine = `040000 tree ${sessionTree}\t${sessionId}`;
+  const logsTree = gitRaw('mktree', projectRoot, wrapperLine);
+  const rootLine = `040000 tree ${logsTree}\t.ses-logs`;
+  const rootTree = gitRaw('mktree', projectRoot, rootLine);
+
+  // Check if branch already exists (for parent chaining)
+  let parentArg = '';
+  try {
+    const existing = git(`rev-parse ${refPath}`, projectRoot);
+    parentArg = `-p ${existing}`;
+  } catch {
+    // orphan - no parent
+  }
+
+  // Create commit
+  const timestamp = new Date().toISOString().replace('T', ' ').split('.')[0];
+  const message = `session ${sessionShort} @ ${timestamp}`;
+  const commitSha = git(
+    `commit-tree ${rootTree} ${parentArg} -m "${message}"`,
+    projectRoot
+  );
+
+  // Update branch ref
+  git(`update-ref ${refPath} ${commitSha}`, projectRoot);
+
+  // Save branch info to state
+  const stateFile = join(sessionDir, 'state.json');
+  try {
+    const state = JSON.parse(readFileSync(stateFile, 'utf-8'));
+    state.shadow_branch = branchName;
+    const { writeFileSync } = await import('fs');
+    writeFileSync(stateFile, JSON.stringify(state, null, 2));
+  } catch { /* best effort */ }
+}
+
+/**
+ * List all shadow branches in the repo.
+ */
+export function listShadowBranches(projectRoot) {
+  try {
+    const output = git('branch --list "ses/*"', projectRoot);
+    return output.split('\n').map(b => b.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Show shadow branch info.
+ */
+export function shadowInfo(projectRoot, branchName) {
+  try {
+    const log = git(`log ${branchName} --oneline -5`, projectRoot);
+    const files = git(`ls-tree -r --name-only ${branchName}`, projectRoot);
+    return { log, files: files.split('\n') };
+  } catch {
+    return null;
+  }
+}
+

package/lib/init.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from 'fs';
+import { join } from 'path';
+import { getProjectRoot } from './config.js';
+
+const HOOK_TYPES = [
+  'SessionStart', 'SessionEnd', 'UserPromptSubmit',
+  'PreToolUse', 'PostToolUse', 'Notification', 'Stop',
+];
+
+const SES_COMMAND = (hookType) => `ses log ${hookType.replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, '')}`;
+
+export default async function init(args) {
+  const cwd = getProjectRoot();
+  const claudeDir = join(cwd, '.claude');
+  const settingsFile = join(claudeDir, 'settings.json');
+
+  console.log('Initializing ses-cli hooks...\n');
+
+  mkdirSync(claudeDir, { recursive: true });
+
+  // Load existing settings
+  let settings = {};
+  if (existsSync(settingsFile)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsFile, 'utf-8'));
+    } catch {
+      console.log('Warning: could not parse settings.json, creating new');
+    }
+  }
+  if (!settings.hooks) settings.hooks = {};
+
+  // Register hooks
+  let added = 0, skipped = 0;
+
+  for (const hookType of HOOK_TYPES) {
+    const command = SES_COMMAND(hookType);
+    const existing = settings.hooks[hookType] || [];
+
+    const alreadyExists = existing.some(entry =>
+      entry.hooks?.some(h => h.command?.includes('ses log'))
+    );
+
+    if (alreadyExists) {
+      skipped++;
+      continue;
+    }
+
+    const catchAll = existing.find(entry => entry.matcher === '');
+    if (catchAll) {
+      catchAll.hooks = catchAll.hooks || [];
+      catchAll.hooks.push({ type: 'command', command });
+    } else {
+      existing.push({ matcher: '', hooks: [{ type: 'command', command }] });
+    }
+
+    settings.hooks[hookType] = existing;
+    added++;
+  }
+
+  writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + '\n');
+
+  console.log(`Added: ${added} hooks | Skipped: ${skipped} (already registered)`);
+  console.log('Hook types:', HOOK_TYPES.join(', '));
+
+  // Create .ses-logs and update .gitignore
+  mkdirSync(join(cwd, '.ses-logs'), { recursive: true });
+
+  const gitignoreFile = join(cwd, '.gitignore');
+  if (existsSync(gitignoreFile)) {
+    const content = readFileSync(gitignoreFile, 'utf-8');
+    if (!content.includes('.ses-logs')) {
+      appendFileSync(gitignoreFile, '\n# ses-cli logs\n.ses-logs/\n');
+    }
+  } else {
+    writeFileSync(gitignoreFile, '# ses-cli logs\n.ses-logs/\n');
+  }
+
+  console.log('\nLogs: .ses-logs/ (project-local)');
+  console.log('Shadow branches: ses/<commit>-<session> (git)');
+  console.log('\nDone. Start Claude Code and hooks will log automatically.');
+}