@claudemini/shit-cli 1.0.3

package/bin/shit.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+const commands = {
+  init:   'Initialize hooks in .claude/settings.json',
+  log:    'Log a hook event (called by hooks)',
+  list:   'List all sessions',
+  view:   'View session details',
+  query:  'Query session memory (cross-session)',
+  shadow: 'List shadow branches',
+  clean:  'Clean old sessions',
+  help:   'Show help',
+};
+
+function showHelp() {
+  console.log('shit-cli - Session Hook Intelligence Tracker\n');
+  console.log('Usage: shit <command> [options]\n');
+  console.log('Commands:');
+  Object.entries(commands).forEach(([cmd, desc]) => {
+    console.log(`  ${cmd.padEnd(10)} ${desc}`);
+  });
+  console.log('\nExamples:');
+  console.log('  shit init                        # Register hooks');
+  console.log('  shit list                        # List sessions');
+  console.log('  shit view <session-id>           # View session');
+  console.log('  shit view <session-id> --json    # View with JSON data');
+  console.log('  shit query --recent=5            # Recent 5 sessions');
+  console.log('  shit query --file=src/app.ts     # Sessions that touched file');
+  console.log('  shit query --type=bugfix         # Filter by session type');
+  console.log('  shit query --risk=high --json    # High-risk sessions as JSON');
+  console.log('  shit shadow                      # List shadow branches');
+  console.log('  shit clean --days=7              # Clean old sessions');
+}
+
+if (!command || command === 'help' || command === '--help') {
+  showHelp();
+  process.exit(0);
+}
+
+if (command === '--version' || command === '-v') {
+  const { readFileSync } = await import('fs');
+  const { fileURLToPath } = await import('url');
+  const { dirname, join } = await import('path');
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+  console.log(`shit-cli v${pkg.version}`);
+  process.exit(0);
+}
+
+try {
+  const mod = await import(`../lib/${command}.js`);
+  await mod.default(args.slice(1));
+} catch (error) {
+  if (error.code === 'ERR_MODULE_NOT_FOUND') {
+    console.error(`Unknown command: ${command}`);
+    process.exit(1);
+  }
+  throw error;
+}

package/lib/clean.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+import { readdirSync, statSync, rmSync } from 'fs';
+import { join } from 'path';
+import { getProjectRoot, getLogDir, SESSION_ID_REGEX } from './config.js';
+
+export default async function clean(args) {
+  const logDir = getLogDir(getProjectRoot());
+  const daysArg = args.find(a => a.startsWith('--days='));
+  const days = daysArg ? parseInt(daysArg.split('=')[1]) : 7;
+  const dryRun = args.includes('--dry-run');
+  const cutoffTime = Date.now() - days * 24 * 60 * 60 * 1000;
+
+  try {
+    const entries = readdirSync(logDir);
+    const old = entries
+      .filter(name => SESSION_ID_REGEX.test(name))
+      .map(id => {
+        const dir = join(logDir, id);
+        return { id, dir, mtime: statSync(dir).mtime.getTime() };
+      })
+      .filter(s => s.mtime < cutoffTime);
+
+    if (old.length === 0) {
+      console.log(`No sessions older than ${days} days.`);
+      return;
+    }
+
+    console.log(`${old.length} session(s) older than ${days} days:`);
+    old.forEach(s => {
+      const age = Math.floor((Date.now() - s.mtime) / 86400000);
+      console.log(`  ${s.id.slice(0, 8)}... (${age}d)`);
+    });
+
+    if (dryRun) {
+      console.log('\n[DRY RUN] No files deleted.');
+    } else {
+      old.forEach(s => rmSync(s.dir, { recursive: true, force: true }));
+      console.log(`\nDeleted ${old.length} session(s).`);
+    }
+  } catch (error) {
+    if (error.code === 'ENOENT') console.log('No log directory found.');
+    else throw error;
+  }
+}

package/lib/config.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { join, relative } from 'path';
+import { execSync } from 'child_process';
+
+export const SESSION_ID_REGEX = /^[a-f0-9-]{36}$/;
+
+export function getProjectRoot() {
+  try {
+    return execSync('git rev-parse --show-toplevel', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch {
+    return process.cwd();
+  }
+}
+
+export function getLogDir(projectRoot) {
+  return process.env.SHIT_LOG_DIR || join(projectRoot || getProjectRoot(), '.shit-logs');
+}
+
+export function toRelative(projectRoot, filePath) {
+  if (!filePath || !filePath.startsWith('/')) return filePath;
+  return relative(projectRoot, filePath) || filePath;
+}

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: shit/<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: shit/<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 = `shit/${headShort}-${sessionShort}`;
+  const refPath = `refs/heads/${branchName}`;
+
+  // Build tree from session directory
+  const sessionTree = buildTree(projectRoot, sessionDir);
+  if (!sessionTree) return;
+
+  // Wrap session files under .shit-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.shit-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 "shit/*"', 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 SHIT_COMMAND = (hookType) => `shit 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 shit-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 = SHIT_COMMAND(hookType);
+    const existing = settings.hooks[hookType] || [];
+
+    const alreadyExists = existing.some(entry =>
+      entry.hooks?.some(h => h.command?.includes('shit 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 .shit-logs and update .gitignore
+  mkdirSync(join(cwd, '.shit-logs'), { recursive: true });
+
+  const gitignoreFile = join(cwd, '.gitignore');
+  if (existsSync(gitignoreFile)) {
+    const content = readFileSync(gitignoreFile, 'utf-8');
+    if (!content.includes('.shit-logs')) {
+      appendFileSync(gitignoreFile, '\n# shit-cli logs\n.shit-logs/\n');
+    }
+  } else {
+    writeFileSync(gitignoreFile, '# shit-cli logs\n.shit-logs/\n');
+  }
+
+  console.log('\nLogs: .shit-logs/ (project-local)');
+  console.log('Shadow branches: shit/<commit>-<session> (git)');
+  console.log('\nDone. Start Claude Code and hooks will log automatically.');
+}

package/lib/list.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { getProjectRoot, getLogDir, SESSION_ID_REGEX } from './config.js';
+
+export default async function list(args) {
+  const logDir = getLogDir(getProjectRoot());
+
+  if (!existsSync(logDir)) {
+    console.log('No log directory found. Run "shit init" first.');
+    return;
+  }
+
+  const entries = readdirSync(logDir);
+  const sessions = entries
+    .filter(name => SESSION_ID_REGEX.test(name))
+    .map(id => {
+      const dir = join(logDir, id);
+      const metaFile = join(dir, 'metadata.json');
+      const stateFile = join(dir, 'state.json');
+      try {
+        const meta = JSON.parse(readFileSync(metaFile, 'utf-8'));
+        let state = null;
+        if (existsSync(stateFile)) {
+          state = JSON.parse(readFileSync(stateFile, 'utf-8'));
+        }
+        return { id, meta, state, mtime: statSync(dir).mtime };
+      } catch { return null; }
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.mtime - a.mtime);
+
+  if (sessions.length === 0) {
+    console.log('No sessions found.');
+    return;
+  }
+
+  console.log(`${sessions.length} session(s):\n`);
+
+  sessions.forEach((s, i) => {
+    const m = s.meta;
+    const st = s.state;
+    const dur = m.duration_minutes ?? (st?.start_time && st?.last_time
+      ? Math.round((new Date(st.last_time) - new Date(st.start_time)) / 60000) : 0);
+    const type = m.type || 'unknown';
+    const risk = m.risk || '-';
+    const intent = m.intent || '';
+    const files = (m.files_touched || 0);
+    const errs = (m.errors || 0);
+    const shadow = st?.shadow_branch ? ` [${st.shadow_branch}]` : '';
+    const date = new Date(m.last_updated).toLocaleString();
+
+    console.log(`${i + 1}. ${s.id.slice(0, 8)}  [${type}]  risk:${risk}`);
+    if (intent) {
+      console.log(`   ${intent.slice(0, 100)}`);
+    }
+    console.log(`   ${dur}min | ${m.event_count} events | ${m.tool_calls || 0} tools | ${files} files | ${errs} errors${shadow}`);
+    console.log(`   ${date}`);
+    console.log('');
+  });
+}