@claudemini/shit-cli 1.4.0 → 1.6.0

package/README.md

@@ -2,69 +2,73 @@
 
 **S**ession-based **H**ook **I**ntelligence **T**racker
 
-A memory system for human-AI interactions, designed to provide reliable data support for code review automation.
+A zero-dependency memory system for human-AI coding sessions. Tracks what happened, classifies intent and risk, and provides structured data for code review automation.
 
-## Design Vision
+Supports **Claude Code**, **Gemini CLI**, **Cursor**, and **OpenCode**.
 
-1. **Human-AI Interaction Memory System** - Long-term memory, not temporary logs
-2. **Code Review Bot Data Support** - Structured semantic data for intelligent code review
-
-See [DESIGN_PHILOSOPHY.md](./DESIGN_PHILOSOPHY.md) for detailed design rationale.
-
-## Installation
+## Quick Start
 
 ```bash
-cd shit-cli
-npm link
-```
+npm install -g @claudemini/shit-cli
 
-Or use directly:
-```bash
-node bin/shit.js <command>
+cd /path/to/your/project
+shit enable          # Setup hooks + .shit-logs
+# ... use Claude Code normally ...
+shit list            # See sessions
+shit status          # Check current session
 ```
 
-## Usage
-
-### Initialize hooks
+## Installation
 
 ```bash
-cd /path/to/your/project
-shit init
+npm install -g @claudemini/shit-cli
 ```
 
-Registers all hooks in `.claude/settings.json` automatically.
-
-### List sessions
+Or use directly without installing:
 
 ```bash
-shit list
+npx @claudemini/shit-cli <command>
 ```
 
-Output:
-```
-3 session(s):
+## Commands
 
-1. f608c31e  [bugfix]  risk:medium
-   Fix auth timeout by adjusting retry logic
-   45min | 42 events | 28 tools | 3 files | 0 errors
-   2/27/2026, 3:15:00 PM
+### Setup
 
-2. a1b2c3d4  [feature]  risk:low
-   Add user profile endpoint
-   30min | 28 events | 15 tools | 2 files | 0 errors
-   2/26/2026, 10:30:00 AM
+```bash
+shit enable                    # Enable for Claude Code (default)
+shit enable gemini-cli         # Enable for Gemini CLI
+shit enable --all              # Enable for all supported agents
+shit enable --checkpoint       # Also create checkpoints on git commit
+shit disable                   # Remove hooks (keep data)
+shit disable --clean           # Remove hooks and all data
+shit init                      # Low-level: register hooks in .claude/settings.json
 ```
 
-### View session details
+### Session Tracking
 
 ```bash
-shit view f608c31e-453c-435a-b0e2-3116dc56ad71
-shit view f608c31e-453c-435a-b0e2-3116dc56ad71 --json  # Include raw JSON
+shit status                    # Show current session + git info
+shit list                      # List all sessions with type, risk, intent
+shit view <session-id>         # View semantic session report
+shit view <session-id> --json  # Include raw JSON data
+shit review [session-id]       # Run structured code review from session data
+shit review --json             # Machine-readable findings (structured schema)
+shit review --recent=3 --md    # Aggregated Markdown report for PR comments
+shit review --strict --fail-on=medium  # CI gate by severity threshold
+shit explain <session-id>      # Human-friendly explanation of a session
+shit explain <commit-sha>      # Explain a commit via its checkpoint
 ```
 
-Output includes: intent, changes by category, tools, commands, review hints (tests run, build verified, config changed, etc.).
+`shit review` options:
+- `--recent=<n>` review latest `n` sessions (default `1`)
+- `--all` review all sessions in `.shit-logs`
+- `--min-severity=<info|low|medium|high|critical>` filter findings
+- `--fail-on=<info|low|medium|high|critical>` strict-mode failure threshold (default `high`)
+- `--strict` exit code `1` when findings reach `--fail-on`
+- `--json` output structured JSON
+- `--markdown` / `--md` output Markdown
 
-### Query session memory
+### Cross-Session Queries
 
 ```bash
 shit query --recent=5                         # Recent 5 sessions
@@ -74,70 +78,93 @@ shit query --risk=high                        # High-risk sessions
 shit query --type=feature --json              # JSON output for bot consumption
 ```
 
-### Shadow branches
+### Checkpoints & Recovery
 
 ```bash
-shit shadow                     # List shadow branches
-shit shadow info <branch>       # Show branch details
+shit checkpoints               # List all checkpoints
+shit commit                    # Manually create checkpoint for current HEAD
+shit rewind <checkpoint>       # Rollback to a checkpoint (git reset --hard)
+shit rewind --interactive      # Choose from available checkpoints
+shit resume <checkpoint>       # Restore session data from a checkpoint
+shit reset --force             # Delete checkpoint for current HEAD
 ```
 
-### Clean old sessions
+### Maintenance
 
 ```bash
-shit clean --days=7 --dry-run   # Preview
-shit clean --days=7             # Delete sessions older than 7 days
+shit doctor                    # Diagnose issues (corrupted state, stuck sessions)
+shit doctor --fix              # Auto-fix detected issues
+shit shadow                    # List shadow branches
+shit shadow info <branch>      # Show branch details
+shit clean --days=7 --dry-run  # Preview cleanup
+shit clean --days=7            # Delete sessions older than 7 days
+shit summarize <session-id>    # Generate AI summary (requires API key)
 ```
 
-## Commands
+## Command Reference
 
 | Command | Description |
 |---------|-------------|
-| `init` | Initialize hooks in .claude/settings.json |
-| `log <hook-type>` | Log a hook event from stdin (called by hooks) |
+| `enable` | Enable shit-cli in repository (multi-agent support) |
+| `disable` | Remove hooks, optionally clean data |
+| `status` | Show current session and git info |
+| `init` | Register hooks in .claude/settings.json |
+| `log <type>` | Log a hook event from stdin (called by hooks) |
 | `list` | List all sessions with type, intent, risk |
-| `view <session-id> [--json]` | View semantic session report |
-| `query [options]` | Query session memory across sessions |
-| `shadow [info <branch>]` | List or inspect shadow branches |
-| `clean [--days=N] [--dry-run]` | Clean old sessions |
-| `help` | Show help |
-
-## Architecture
+| `view <id>` | View semantic session report |
+| `review [id]` | Run structured code review (single or multi-session) |
+| `query` | Query session memory across sessions |
+| `explain <id>` | Human-friendly explanation of a session or commit |
+| `commit` | Create checkpoint on git commit |
+| `checkpoints` | List all checkpoints |
+| `rewind <cp>` | Rollback to a checkpoint |
+| `resume <cp>` | Resume session from a checkpoint |
+| `reset` | Delete checkpoint for current HEAD |
+| `summarize <id>` | Generate AI summary for a session |
+| `doctor` | Diagnose and fix issues |
+| `shadow` | List/inspect shadow branches |
+| `clean` | Clean old sessions |
+
+## How It Works
 
 ```
-shit-cli/
-├── bin/shit.js              # CLI entry point
-├── lib/
-│   ├── config.js            # Shared config: getProjectRoot(), getLogDir(), toRelative()
-│   ├── extract.js           # Semantic extraction: intent, changes, classification
-│   ├── report.js            # Report generation: summary.json v2, summary.txt, metadata
-│   ├── session.js           # Session state management + cross-session index
-│   ├── log.js               # Event ingestion dispatcher (stdin → parse → extract → save)
-│   ├── init.js              # shit init (hook registration)
-│   ├── list.js              # shit list (semantic session listing)
-│   ├── view.js              # shit view (semantic report display)
-│   ├── query.js             # shit query (cross-session memory queries)
-│   ├── clean.js             # shit clean (session cleanup)
-│   ├── shadow.js            # shit shadow (branch listing)
-│   └── git-shadow.js        # Git plumbing for shadow branches
+Human <-> AI Agent (Claude Code, Gemini CLI, ...)
+              | (hooks)
+         Event Ingestion (log.js)
+              |
+         Semantic Extraction (extract.js)
+              |
+         Session State (session.js) + Reports (report.js)
+              |
+         Memory System (.shit-logs/ + index.json)
+              |
+         Code Review Bot / Human Queries
 ```
 
+1. **Ingestion** - Hooks fire on every agent event (tool use, prompts, session start/end). Events are appended to `events.jsonl`.
+2. **Extraction** - Each event updates incremental state. Intent, change categories, and risk are computed using rule-based pattern matching (zero latency, zero cost, fully offline).
+3. **Reports** - `summary.json` (bot-readable), `summary.txt` (human-readable), `context.md`, `metadata.json`, and `prompts.txt` are regenerated on every event.
+4. **Checkpoints** - On session end or git commit, session data is committed to an orphan git branch using plumbing commands (no working tree impact).
+
 ## Data Model
 
 ### Session Directory
 
 ```
 .shit-logs/
-├── index.json                              # Cross-session index (file history, types)
+├── index.json                              # Cross-session index
 └── <session-id>/
     ├── events.jsonl                        # Raw hook events
     ├── state.json                          # Incremental processing state
-    ├── summary.json                        # Bot data interface (v2 schema)
-    ├── summary.txt                         # Human-readable semantic report
+    ├── summary.json                        # Bot data interface (v2)
+    ├── summary.txt                         # Human-readable report
+    ├── context.md                          # Session context (Entire-style)
     ├── prompts.txt                         # User prompts with timestamps
-    └── metadata.json                       # Lightweight session metadata
+    ├── metadata.json                       # Lightweight session metadata
+    └── ai-summary.md                       # AI-generated summary (optional)
 ```
 
-### summary.json v2 Schema
+### summary.json v2
 
 ```json
 {
@@ -153,56 +180,27 @@ shit-cli/
     "summary": "Fixed: Fix authentication timeout issue"
   },
   "changes": {
-    "files": [{
-      "path": "src/auth/auth.service.ts",
-      "category": "source",
-      "operations": ["edit"],
-      "editCount": 2,
-      "editSummary": "Modified timeout logic"
-    }],
+    "files": [{ "path": "src/auth.ts", "category": "source", "operations": ["edit"] }],
     "summary": { "source": 3, "test": 1 }
   },
   "activity": {
     "tools": { "Read": 15, "Edit": 3, "Bash": 5 },
-    "commands": {
-      "test": ["npm run test"],
-      "git": ["git status"]
-    },
+    "commands": { "test": ["npm run test"], "git": ["git status"] },
     "errors": []
   },
   "review_hints": {
     "tests_run": true,
     "build_verified": false,
-    "files_without_tests": ["src/auth/auth.service.ts"],
+    "files_without_tests": ["src/auth.ts"],
     "large_change": false,
     "config_changed": false,
     "migration_added": false
   },
-  "prompts": ["Fix the auth timeout bug", "Run the tests"],
+  "prompts": [{ "time": "...", "text": "Fix the auth timeout bug" }],
   "scope": ["auth"]
 }
 ```
 
-### Cross-Session Index
-
-```json
-{
-  "project": "my-project",
-  "sessions": [{
-    "id": "f608c31e...",
-    "date": "2026-02-27",
-    "type": "bugfix",
-    "intent": "Fix auth timeout",
-    "files": ["src/auth/auth.service.ts"],
-    "duration": 45,
-    "risk": "medium"
-  }],
-  "file_history": {
-    "src/auth/auth.service.ts": ["f608c31e...", "a1b2c3d4..."]
-  }
-}
-```
-
 ## Session Types
 
 | Type | Description |
@@ -219,19 +217,20 @@ shit-cli/
 | `style` | Formatting, UI |
 | `security` | Security-related |
 | `perf` | Performance optimization |
-| `unknown` | Unclassified |
 
 ## Risk Levels
 
-- **low**: Few files, no config/migration changes, tests run
-- **medium**: Multiple files, some config changes
-- **high**: Many files (>10), migration changes, infra changes without tests
+- **low** - Few files, no config/migration changes, tests run
+- **medium** - Multiple files, some config changes
+- **high** - Many files (>10), migration changes, infra changes without tests
 
 ## Bot Integration
 
 ```javascript
+import { readFileSync } from 'fs';
+
 // Read session data
-const summary = JSON.parse(fs.readFileSync('.shit-logs/<id>/summary.json'));
+const summary = JSON.parse(readFileSync('.shit-logs/<id>/summary.json', 'utf-8'));
 
 // Check review hints
 if (!summary.review_hints.tests_run && summary.changes.files.length > 0) {
@@ -242,16 +241,40 @@ if (summary.review_hints.migration_added) {
 }
 
 // Query file history via index
-const index = JSON.parse(fs.readFileSync('.shit-logs/index.json'));
+const index = JSON.parse(readFileSync('.shit-logs/index.json', 'utf-8'));
 const history = index.file_history['src/auth/auth.service.ts'];
-if (history.length > 3) {
+if (history && history.length > 3) {
   review.note('This file has been modified frequently');
 }
 ```
 
+## AI Summary
+
+Set one of these environment variables to enable AI-powered session summaries:
+
+```bash
+export OPENAI_API_KEY=sk-...      # Uses gpt-4o-mini by default
+export ANTHROPIC_API_KEY=sk-...   # Uses claude-3-haiku by default
+```
+
+Then run:
+```bash
+shit summarize <session-id>
+```
+
 ## Environment Variables
 
-- `SHIT_LOG_DIR`: Custom log directory (default: `./.shit-logs` in project root)
+| Variable | Description |
+|----------|-------------|
+| `SHIT_LOG_DIR` | Custom log directory (default: `.shit-logs` in project root) |
+| `OPENAI_API_KEY` | Enable AI summaries via OpenAI |
+| `ANTHROPIC_API_KEY` | Enable AI summaries via Anthropic |
+
+## Security
+
+- Session logs are stored locally in `.shit-logs/` (added to `.gitignore` automatically)
+- Secrets (API keys, tokens, passwords) are automatically redacted when writing to shadow branches
+- Checkpoint data uses git plumbing commands — no impact on your working tree
 
 ## License
 

package/bin/shit.js

@@ -13,6 +13,7 @@ const commands = {
   list:        'List all sessions',
   checkpoints: 'List all checkpoints',
   view:        'View session details',
+  review:      'Run structured code review for a session',
   query:       'Query session memory (cross-session)',
   explain:     'Explain a session or commit',
   summarize:   'Generate AI summary for a session',
@@ -37,6 +38,8 @@ function showHelp() {
   console.log('  shit status                      # Show current session');
   console.log('  shit list                        # List sessions');
   console.log('  shit view <session-id>           # View session');
+  console.log('  shit review [session-id]         # Structured code review');
+  console.log('  shit review --recent=3 --md      # Markdown review for latest 3 sessions');
   console.log('  shit rewind <checkpoint>         # Rollback to checkpoint');
   console.log('  shit resume <checkpoint>         # Resume from checkpoint');
   console.log('  shit doctor --fix                # Fix stuck sessions');
@@ -61,13 +64,21 @@ if (command === '--version' || command === '-v') {
   process.exit(0);
 }
 
+if (!Object.prototype.hasOwnProperty.call(commands, command)) {
+  console.error(`Unknown command: ${command}`);
+  process.exit(1);
+}
+
 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);
+  if (typeof mod.default !== 'function') {
+    throw new Error(`Command module "${command}" has no default function export`);
   }
-  throw error;
+  const exitCode = await mod.default(args.slice(1));
+  if (Number.isInteger(exitCode) && exitCode !== 0) {
+    process.exitCode = exitCode;
+  }
+} catch (error) {
+  console.error(`Failed to run command "${command}": ${error.message}`);
+  process.exit(1);
 }

package/lib/checkpoint.js

@@ -8,7 +8,7 @@
  *   - Supports multiple agents (Claude Code, Gemini CLI, Cursor, etc.)
  */
 
-import { readdirSync, readFileSync, statSync, writeFileSync } from 'fs';
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'fs';
 import { execSync } from 'child_process';
 import { join, dirname } from 'path';
 import { redactSecrets } from './redact.js';
@@ -149,9 +149,10 @@ export async function commitCheckpoint(projectRoot, sessionDir, sessionId, commi
     return { success: false, reason: 'not a git repo' };
   }
 
-  // Branch naming: shit/checkpoints/v1/YYYY-MM-DD-<short-uuid>
-  const datePart = sessionId.split('-').slice(0, 3).join('-');
-  const uuidPart = sessionId.split('-').slice(3).join('-').slice(0, 8);
+  // Branch naming: shit/checkpoints/v1/YYYY-MM-DD-<session-short>
+  const datePart = new Date().toISOString().slice(0, 10);
+  const sessionCompact = sessionId.toLowerCase().replace(/[^a-f0-9]/g, '');
+  const uuidPart = (sessionCompact.slice(-8) || sessionCompact.slice(0, 8) || 'unknown00').padEnd(8, '0');
   const branchName = `shit/checkpoints/v1/${datePart}-${uuidPart}`;
   const refPath = `refs/heads/${branchName}`;
 
@@ -208,13 +209,6 @@ export async function commitCheckpoint(projectRoot, sessionDir, sessionId, commi
     // best effort
   }
 
-  return {
-    success: true,
-    branch: branchName,
-    commit: commitHash,
-    linked_commit: linkedCommit,
-  };
-
   // Auto-summarize if enabled
   if (autoSummarize) {
     try {
@@ -227,6 +221,13 @@ export async function commitCheckpoint(projectRoot, sessionDir, sessionId, commi
       // Best effort - summarize is optional
     }
   }
+
+  return {
+    success: true,
+    branch: branchName,
+    commit: commitHash,
+    linked_commit: linkedCommit,
+  };
 }
 
 /**
@@ -241,29 +242,35 @@ export function listCheckpoints(projectRoot) {
 
     for (const branch of branches) {
       try {
-        // Extract session info from branch name
+        // Extract session info from branch name (supports current and legacy formats)
         const match = branch.match(/^shit\/checkpoints\/v1\/(\d{4}-\d{2}-\d{2})-([a-f0-9]+)$/);
-        if (match) {
-          const [, date, uuidShort] = match;
-
-          // Get commit info
-          const log = git(`log ${branch} --oneline -1`, projectRoot);
-          const commitMatch = log.match(/^([a-f0-9]+)\s+checkpoint/);
-          const commit = commitMatch ? commitMatch[1] : log.split(' ')[0];
-
-          // Get linked commit from message
-          const fullLog = git(`log ${branch} --format=%B -1`, projectRoot);
-          const linkedMatch = fullLog.match(/@ ([a-f0-9]+)/);
-          const linkedCommit = linkedMatch ? linkedMatch[1] : null;
-
-          checkpoints.push({
-            branch,
-            commit: commit.slice(0, 12),
-            linked_commit: linkedCommit,
-            date,
-            uuid: uuidShort,
-          });
+        const legacyMatch = branch.match(/^shit\/checkpoints\/v1\/([a-f0-9-]+)$/);
+        if (!match && !legacyMatch) {
+          continue;
         }
+
+        const date = match ? match[1] : git(`log ${branch} --format=%cs -1`, projectRoot);
+        const uuidShort = match
+          ? match[2]
+          : ((legacyMatch[1].replace(/[^a-f0-9]/g, '').slice(-8) || legacyMatch[1].slice(0, 8)).toLowerCase());
+
+        // Get commit info
+        const log = git(`log ${branch} --oneline -1`, projectRoot);
+        const commitMatch = log.match(/^([a-f0-9]+)\s+checkpoint/);
+        const commit = commitMatch ? commitMatch[1] : log.split(' ')[0];
+
+        // Get linked commit from message
+        const fullLog = git(`log ${branch} --format=%B -1`, projectRoot);
+        const linkedMatch = fullLog.match(/@ ([a-f0-9]+)/);
+        const linkedCommit = linkedMatch ? linkedMatch[1] : null;
+
+        checkpoints.push({
+          branch,
+          commit: commit.slice(0, 12),
+          linked_commit: linkedCommit,
+          date,
+          uuid: uuidShort,
+        });
       } catch {
         // Skip invalid branches
       }

package/lib/checkpoints.js

@@ -5,24 +5,12 @@
  * Inspired by Entire's checkpoint system
  */
 
-import { existsSync } from 'fs';
-import { join } from 'path';
-import { listCheckpoints, getCheckpoint } from './checkpoint.js';
-
-function findProjectRoot() {
-  let dir = process.cwd();
-  while (dir !== '/') {
-    if (existsSync(join(dir, '.git'))) {
-      return dir;
-    }
-    dir = join(dir, '..');
-  }
-  throw new Error('Not in a git repository');
-}
+import { listCheckpoints } from './checkpoint.js';
+import { getProjectRoot } from './config.js';
 
 export default async function checkpoints(args) {
   try {
-    const projectRoot = findProjectRoot();
+    const projectRoot = getProjectRoot();
     const verbose = args.includes('--verbose') || args.includes('-v');
     const json = args.includes('--json');
 

package/lib/commit.js

@@ -5,25 +5,15 @@
  * Similar to Entire's approach: checkpoint created on git commit
  */
 
-import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, readdirSync, statSync } from 'fs';
 import { join } from 'path';
 import { execSync } from 'child_process';
 import { commitCheckpoint } from './checkpoint.js';
-
-function findProjectRoot() {
-  let dir = process.cwd();
-  while (dir !== '/') {
-    if (existsSync(join(dir, '.git'))) {
-      return dir;
-    }
-    dir = join(dir, '..');
-  }
-  throw new Error('Not in a git repository');
-}
+import { getProjectRoot, SESSION_ID_REGEX } from './config.js';
 
 export default async function commitHook(args) {
   try {
-    const projectRoot = findProjectRoot();
+    const projectRoot = getProjectRoot();
 
     // Get the commit that was just created
     const commitSha = args[0] || execSync('git rev-parse HEAD', { cwd: projectRoot, encoding: 'utf-8' }).trim();
@@ -39,9 +29,11 @@ export default async function commitHook(args) {
     }
 
     // Find the most recent session
-    const { readdirSync, statSync } = await import('fs');
     const sessions = readdirSync(shitLogsDir)
-      .filter(name => name.match(/^\d{4}-\d{2}-\d{2}-[a-f0-9-]+$/))
+      .filter(name => {
+        const fullPath = join(shitLogsDir, name);
+        return SESSION_ID_REGEX.test(name) && statSync(fullPath).isDirectory();
+      })
       .map(name => ({
         name,
         path: join(shitLogsDir, name),

package/lib/config.js

@@ -3,7 +3,9 @@
 import { join, relative } from 'path';
 import { execSync } from 'child_process';
 
-export const SESSION_ID_REGEX = /^[a-f0-9-]{36}$/;
+export const UUID_SESSION_ID_REGEX = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+export const LEGACY_SESSION_ID_REGEX = /^\d{4}-\d{2}-\d{2}-[a-f0-9-]+$/;
+export const SESSION_ID_REGEX = /^(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|\d{4}-\d{2}-\d{2}-[a-f0-9-]+)$/;
 
 export function getProjectRoot() {
   try {