@claudemini/ses-cli

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.

Release 1.5.0

• Stable session/checkpoint/review object model with JSON-first CLI output
• Multi-agent review with claude, codex, qwen, dim, and opencode
• Canonical hook/event normalization across Claude Code, Gemini CLI, Cursor, and OpenCode
• Safer anonymous session handling, webhook envelopes, and checkpoint/session lineage

Quick Start

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

npm install -g @claudemini/ses-cli

Or use directly without installing:

npx @claudemini/ses-cli <command>

Commands

Setup

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

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 --engine=multi-agent --providers=codex,dim,opencode
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:

• --engine=<agent|multi-agent> choose single-agent or multi-provider review
• --providers=<claude|codex|qwen|dim|opencode>[,...] select multi-agent providers
• --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)
• --provider-timeout-ms=<ms> per-provider timeout in multi-agent mode
• --max-provider-parallelism=<n> multi-agent concurrency (0 = full parallel)
• --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)
• --strict exit code 1 when findings reach --fail-on
• --strict-contract escalate provider parse / execution failures
• --json output structured JSON
• --markdown / --md output Markdown

Cross-Session Queries

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

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

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 structured code review (single-agent or multi-agent)
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)
              |
         Canonical Events -> Session State -> Reports
              |
         Session Artifacts (.ses-logs/ + index.json)
              |
         Review Engines / Human Queries / Webhooks

• Ingestion - Hooks fire on every agent event (tool use, prompts, session start/end). Events are appended to events.jsonl.
• Extraction - Each event updates incremental state. Intent, change categories, and risk are computed using rule-based pattern matching (zero latency, zero cost, fully offline).
• Reports - summary.json, metadata.json, context.md, summary.txt, prompts.txt, and review-run.json are stable projections of the session artifact.
• Checkpoints - On session end or git commit, session data is checkpointed into ses/checkpoints/v1/* without changing the working tree.

Configuration

All configuration lives in .ses-logs/config.json. Environment variables override file config.

Full Template

{
  "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)	—
env	Environment variable overrides (lower priority than real env vars)	—

Minimal Examples

OpenAI-compatible provider (e.g. MiniMax, DeepSeek, Together):

{
  "provider": "openai",
  "api_key": "sk-...",
  "model": "your-model-id",
  "openai_base_url": "https://api.your-provider.com/v1"
}

Anthropic:

{
  "provider": "anthropic",
  "api_key": "sk-ant-...",
  "model": "claude-3-haiku-20240307"
}

With webhook:

{
  "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
    ├── review-run.json                     # Latest stable review record
    ├── review.json                         # Full review report
    ├── review.md                           # Markdown review projection
    └── ai-summary.md                       # AI-generated summary (optional)

summary.json v2

{
  "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

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):

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:

{
  "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):

{
  "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

{
  "event": "session.ended",
  "timestamp": "2026-03-03T12:00:00.000Z",
  "payload": { ... }
}

Commands

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:

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:

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

Single-agent review still uses goatchain. Multi-agent review orchestrates external provider CLIs directly.

License