@claudemini/ses-cli 1.4.3

package/README.md

@@ -0,0 +1,465 @@
+[![Typing SVG](https://readme-typing-svg.herokuapp.com?font=Fira+Code&weight=600&size=32&pause=1000&color=4EA7F7&width=435&lines=Session+Event+Sanpshot;Remember+what+your+AI+did)](https://git.io/typing-svg)
+
+
+A memory system for human-AI coding sessions. Tracks what happened, classifies intent and risk, and provides structured data for code review automation.
+
+Supports **Claude Code**, **Gemini CLI**, **Cursor**, and **OpenCode**.
+
+## Quick Start
+
+```bash
+npm install -g @claudemini/ses-cli
+
+cd /path/to/your/project
+ses enable          # Setup hooks + .ses-logs
+# ... use Claude Code normally ...
+ses list            # See sessions
+ses status          # Check current session
+```
+
+## Installation
+
+```bash
+npm install -g @claudemini/ses-cli
+```
+
+Or use directly without installing:
+
+```bash
+npx @claudemini/ses-cli <command>
+```
+
+## Commands
+
+### Setup
+
+```bash
+ses enable                    # Enable for Claude Code (default)
+ses enable gemini-cli         # Enable for Gemini CLI
+ses enable --all              # Enable for all supported agents
+ses enable --checkpoint       # Also create checkpoints on git commit
+ses disable                   # Remove hooks (keep data)
+ses disable --clean           # Remove hooks and all data
+ses init                      # Low-level: register hooks in .claude/settings.json
+```
+
+### Session Tracking
+
+```bash
+ses status                    # Show current session + git info
+ses list                      # List all sessions with type, risk, intent
+ses view <session-id>         # View semantic session report
+ses view <session-id> --json  # Include raw JSON data
+ses review [session-id]       # Run structured code review from session data
+ses review --json             # Machine-readable findings (structured schema)
+ses review                    # goatchain Agent-driven review
+ses review --recent=3 --md    # Aggregated Markdown report for PR comments
+ses review --strict --fail-on=medium  # CI gate by severity threshold
+ses explain <session-id>      # Human-friendly explanation of a session
+ses explain <commit-sha>      # Explain a commit via its checkpoint
+```
+
+`ses review` options:
+- `--recent=<n>` review latest `n` sessions (default `1`)
+- `--all` review all sessions in `.ses-logs`
+- `--min-severity=<info|low|medium|high|critical>` filter findings
+- `--fail-on=<info|low|medium|high|critical>` strict-mode failure threshold (default `high`)
+- `--agent-timeout-ms=<ms>` total timeout for the review agent (default: 60s base + 30s per session)
+- `--allow-worktree-diff` allow worktree fallback diff when checkpoint commits are unavailable
+- `--agent-auto-approve=<bool>` auto approve agent tool calls (default `true`)
+- `--no-agent-auto-approve` disable auto approval for agent tool calls
+- `--agent` deprecated alias (accepted but ignored)
+- `--engine=<name>` deprecated alias (accepted but ignored)
+- `--strict` exit code `1` when findings reach `--fail-on`
+- `--json` output structured JSON
+- `--markdown` / `--md` output Markdown
+
+### Cross-Session Queries
+
+```bash
+ses query --recent=5                         # Recent 5 sessions
+ses query --file=src/auth/auth.service.ts    # Sessions that modified this file
+ses query --type=bugfix                      # All bugfix sessions
+ses query --risk=high                        # High-risk sessions
+ses query --type=feature --json              # JSON output for bot consumption
+```
+
+### Checkpoints & Recovery
+
+```bash
+ses checkpoints               # List all checkpoints
+ses commit                    # Manually create checkpoint for current HEAD
+ses rewind <checkpoint>       # Rollback to a checkpoint (git reset --hard)
+ses rewind --interactive      # Choose from available checkpoints
+ses resume <checkpoint>       # Restore session data from a checkpoint
+ses reset --force             # Delete checkpoint for current HEAD
+```
+
+### Maintenance
+
+```bash
+ses doctor                    # Diagnose issues (corrupted state, stuck sessions)
+ses doctor --fix              # Auto-fix detected issues
+ses shadow                    # List shadow branches
+ses shadow info <branch>      # Show branch details
+ses clean --days=7 --dry-run  # Preview cleanup
+ses clean --days=7            # Delete sessions older than 7 days
+ses summarize <session-id>    # Generate AI summary (requires API key)
+```
+
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `enable` | Enable ses-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 <id>` | View semantic session report |
+| `review [id]` | Run agent-driven code review (goatchain, 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 |
+| `webhook` | Show/test webhook configuration |
+
+## How It Works
+
+```
+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 (.ses-logs/ + index.json)
+              |
+         Agent Review (goatchain) / 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).
+
+## Configuration
+
+All configuration lives in `.ses-logs/config.json`. Environment variables override file config.
+
+### Full Template
+
+```json
+{
+  "provider": "openai",
+  "api_key": "sk-...",
+  "model": "gpt-4o-mini",
+  "openai_base_url": "https://api.openai.com/v1",
+  "openai_endpoint": "",
+  "max_tokens": 1000,
+  "temperature": 0.7,
+
+  "webhooks": {
+    "url": "https://example.com/hook",
+    "events": ["session.ended", "review.completed"],
+    "secret": "",
+    "auth_token": "",
+    "headers": {},
+    "timeout_ms": 5000,
+    "retry": 1
+  },
+
+  "env": {
+    "SES_WEBHOOK_URL": "",
+    "SES_WEBHOOK_SECRET": "",
+    "SES_WEBHOOK_EVENTS": ""
+  }
+}
+```
+
+### Fields
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `provider` | `"openai"` or `"anthropic"` | `"openai"` |
+| `api_key` | API key for the provider | — |
+| `model` | Model ID for summarize / review | `"gpt-4o-mini"` |
+| `openai_base_url` | OpenAI-compatible base URL | `"https://api.openai.com/v1"` |
+| `openai_endpoint` | Full endpoint URL (overrides `openai_base_url`) | — |
+| `max_tokens` | Max tokens for AI summary | `1000` |
+| `temperature` | Temperature for AI summary | `0.7` |
+| `webhooks` | Webhook configuration object (see [Webhook](#webhook)) | — |
+| `env` | Environment variable overrides (lower priority than real env vars) | — |
+
+### Minimal Examples
+
+**OpenAI-compatible provider** (e.g. MiniMax, DeepSeek, Together):
+
+```json
+{
+  "provider": "openai",
+  "api_key": "sk-...",
+  "model": "your-model-id",
+  "openai_base_url": "https://api.your-provider.com/v1"
+}
+```
+
+**Anthropic**:
+
+```json
+{
+  "provider": "anthropic",
+  "api_key": "sk-ant-...",
+  "model": "claude-3-haiku-20240307"
+}
+```
+
+**With webhook**:
+
+```json
+{
+  "provider": "openai",
+  "api_key": "sk-...",
+  "model": "gpt-4o-mini",
+  "webhooks": {
+    "url": "https://hooks.slack.com/services/xxx",
+    "events": ["session.ended", "review.completed"]
+  }
+}
+```
+
+## Data Model
+
+### Session Directory
+
+```
+.ses-logs/
+├── index.json                              # Cross-session index
+└── <session-id>/
+    ├── events.jsonl                        # Raw hook events
+    ├── state.json                          # Incremental processing state
+    ├── 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
+    └── ai-summary.md                       # AI-generated summary (optional)
+```
+
+### summary.json v2
+
+```json
+{
+  "version": "2.0",
+  "session": {
+    "id": "f608c31e...",
+    "start": "2026-02-27T10:00:00Z",
+    "end": "2026-02-27T10:45:00Z",
+    "duration_minutes": 45,
+    "type": "bugfix",
+    "intent": "Fix authentication timeout issue",
+    "risk": "medium",
+    "summary": "Fixed: Fix authentication timeout issue"
+  },
+  "changes": {
+    "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"] },
+    "errors": []
+  },
+  "review_hints": {
+    "tests_run": true,
+    "build_verified": false,
+    "files_without_tests": ["src/auth.ts"],
+    "large_change": false,
+    "config_changed": false,
+    "migration_added": false
+  },
+  "prompts": [{ "time": "...", "text": "Fix the auth timeout bug" }],
+  "scope": ["auth"]
+}
+```
+
+## Session Types
+
+| Type | Description |
+|------|-------------|
+| `bugfix` | Bug fixes |
+| `feature` | New features |
+| `refactor` | Code restructuring |
+| `debug` | Investigation/debugging |
+| `test` | Test writing/updates |
+| `docs` | Documentation |
+| `devops` | CI/CD, deployment |
+| `upgrade` | Dependency updates |
+| `config` | Configuration changes |
+| `style` | Formatting, UI |
+| `security` | Security-related |
+| `perf` | Performance optimization |
+
+## 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
+
+## Bot Integration
+
+```javascript
+import { readFileSync } from 'fs';
+
+// Read session data
+const summary = JSON.parse(readFileSync('.ses-logs/<id>/summary.json', 'utf-8'));
+
+// Check review hints
+if (!summary.review_hints.tests_run && summary.changes.files.length > 0) {
+  review.warn('Files modified but no tests run');
+}
+if (summary.review_hints.migration_added) {
+  review.flag('Database migration requires careful review');
+}
+
+// Query file history via index
+const index = JSON.parse(readFileSync('.ses-logs/index.json', 'utf-8'));
+const history = index.file_history['src/auth/auth.service.ts'];
+if (history && history.length > 3) {
+  review.note('This file has been modified frequently');
+}
+```
+
+## Webhook
+
+ses-cli can send webhook notifications to external systems (Slack, Lark, CI, custom platforms) when key events occur.
+
+### Events
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `session.ended` | Session ends (hook `session-end` / `stop`) | `summary.json` content |
+| `review.completed` | `ses review` finishes | Review report |
+
+### Configuration
+
+Webhook supports three configuration sources (highest priority first):
+
+**1. Environment variables** (highest priority):
+
+```bash
+export SES_WEBHOOK_URL=https://example.com/hook
+export SES_WEBHOOK_SECRET=my-secret        # HMAC-SHA256 signing
+export SES_WEBHOOK_AUTH_TOKEN=bearer-token  # Bearer auth (alternative to secret)
+export SES_WEBHOOK_EVENTS=session.ended,review.completed
+```
+
+**2. `.ses-logs/config.json` `env` field**:
+
+```json
+{
+  "env": {
+    "SES_WEBHOOK_URL": "https://example.com/hook",
+    "SES_WEBHOOK_SECRET": "my-secret",
+    "SES_WEBHOOK_EVENTS": "session.ended,review.completed"
+  }
+}
+```
+
+**3. `.ses-logs/config.json` `webhooks` field** (lowest priority):
+
+```json
+{
+  "webhooks": {
+    "url": "https://example.com/hook",
+    "events": ["session.ended", "review.completed"],
+    "secret": "hmac-secret-key",
+    "headers": { "X-Custom": "value" },
+    "timeout_ms": 5000,
+    "retry": 1
+  }
+}
+```
+
+### Authentication
+
+- **HMAC-SHA256** — Set `secret` or `SES_WEBHOOK_SECRET`. Adds `X-Signature-256: sha256=<hex>` header (GitHub-compatible format).
+- **Bearer token** — Set `auth_token` or `SES_WEBHOOK_AUTH_TOKEN`. Adds `Authorization: Bearer <token>` header.
+- If neither is set, requests are sent without authentication.
+
+### Payload Format
+
+```json
+{
+  "event": "session.ended",
+  "timestamp": "2026-03-03T12:00:00.000Z",
+  "payload": { ... }
+}
+```
+
+### Commands
+
+```bash
+ses webhook              # Show current webhook configuration
+ses webhook --test       # Send a test ping to the configured URL
+```
+
+## 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 OPENAI_BASE_URL=https://api.openai.com/v1  # Optional: OpenAI-compatible base URL
+export AI_MODEL=gpt-5-mini         # Optional: universal model override (all providers)
+export ANTHROPIC_API_KEY=sk-...   # Uses claude-3-haiku by default
+```
+
+Then run:
+```bash
+ses summarize <session-id>
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SES_LOG_DIR` | Custom log directory (default: `.ses-logs` in project root) |
+| `OPENAI_API_KEY` | Enable AI summaries via OpenAI |
+| `OPENAI_BASE_URL` | OpenAI-compatible base URL for summaries (default: `https://api.openai.com/v1`) |
+| `OPENAI_ENDPOINT` | Full OpenAI-compatible endpoint (overrides `OPENAI_BASE_URL`) |
+| `AI_MODEL` | Universal model override for summaries (applies to all providers) |
+| `OPENAI_MODEL` | OpenAI-only model override (takes precedence over `AI_MODEL` for OpenAI) |
+| `ANTHROPIC_API_KEY` | Enable AI summaries via Anthropic |
+| `ANTHROPIC_MODEL` | Anthropic-only model override (takes precedence over `AI_MODEL` for Anthropic) |
+| `SES_REVIEW_AGENT_TIMEOUT_MS` | Agent review timeout in milliseconds (default: 60s base + 30s per session) |
+| `SES_REVIEW_AUTO_APPROVE` | Auto approve agent tool calls (`true`/`false`, default: `true`) |
+| `SES_WEBHOOK_URL` | Webhook endpoint URL |
+| `SES_WEBHOOK_SECRET` | HMAC-SHA256 signing secret for webhooks |
+| `SES_WEBHOOK_AUTH_TOKEN` | Bearer token for webhook authentication |
+| `SES_WEBHOOK_EVENTS` | Comma-separated list of webhook events to subscribe to |
+
+`ses summarize` also accepts OpenAI-compatible responses where completion text is returned via `reasoning_content` instead of `content`.
+
+## Security
+
+- Session logs are stored locally in `.ses-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
+
+## Acknowledgements
+
+Special thanks to [goatchain](https://www.npmjs.com/package/goatchain) for powering the agent-driven review workflow in `ses review`.
+
+## License
+

package/bin/ses.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+const commands = {
+  enable:      'Enable ses-cli in repository',
+  disable:     'Remove ses-cli hooks',
+  status:      'Show current session status',
+  init:        'Initialize hooks in .claude/settings.json',
+  log:         'Log a hook event (called by hooks)',
+  commit:      'Create checkpoint on git commit (hook)',
+  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',
+  rewind:      'Rollback to previous checkpoint',
+  resume:      'Resume session from checkpoint',
+  reset:       'Delete checkpoint for current HEAD',
+  doctor:      'Fix or clean stuck sessions',
+  shadow:      'List shadow branches',
+  clean:       'Clean old sessions',
+  webhook:     'Manage webhook configuration',
+  help:        'Show help',
+};
+
+function showHelp() {
+  console.log('ses-cli - Session Hook Intelligence Tracker\n');
+  console.log('Usage: ses <command> [options]\n');
+  console.log('Commands:');
+  Object.entries(commands).forEach(([cmd, desc]) => {
+    console.log(`  ${cmd.padEnd(10)} ${desc}`);
+  });
+  console.log('\nExamples:');
+  console.log('  ses enable                      # Enable ses-cli in repo');
+  console.log('  ses status                      # Show current session');
+  console.log('  ses list                        # List sessions');
+  console.log('  ses view <session-id>           # View session');
+  console.log('  ses review [session-id]         # Structured code review');
+  console.log('  ses review --recent=3 --md      # Markdown review for latest 3 sessions');
+  console.log('  ses rewind <checkpoint>         # Rollback to checkpoint');
+  console.log('  ses resume <checkpoint>         # Resume from checkpoint');
+  console.log('  ses doctor --fix                # Fix stuck sessions');
+  console.log('  ses query --recent=5            # Recent 5 sessions');
+  console.log('  ses query --file=src/app.ts     # Sessions that touched file');
+  console.log('  ses shadow                      # List shadow branches');
+  console.log('  ses disable --clean             # Remove ses-cli and data');
+}
+
+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(`ses-cli v${pkg.version}`);
+  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`);
+  if (typeof mod.default !== 'function') {
+    throw new Error(`Command module "${command}" has no default function export`);
+  }
+  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);
+}