@claudemini/ses-cli

ses-cli

A CLI memory system for human-AI coding sessions.

ses-cli records agent activity as structured session artifacts, keeps checkpoint history, and adds query/review tooling on top of those artifacts.

Release 1.8.0

Checkpoint system aligned with Entire CLI

• Per-turn checkpoints: SaveStep triggers on every TurnEnd/SubagentEnd/Compaction, not just session end
• Shadow branches now contain full working tree snapshots (directly restorable via git checkout)
• Pre-push hook auto-pushes ses/committed/v1 to remote
• Post-commit hook installed by default (--no-checkpoint to skip)
• context.md on committed branch includes full conversation (prompt + AI response per turn)

Unified state system

• Single V2 state pipeline replaces dual V2/legacy system
• Tool tracking (tool_counts, file_ops, errors) merged into SessionStateV2
• Turn pairing happens immediately on AI response (no more waiting for session end)
• files_touched derived from actual tool operations, not git status

5-platform data collection

• Claude Code — full hook integration (prompt, response, tools, tokens)
• Codex — native notify hook, zero daemon (notify = ["ses", "codex-notify"])
• OpenCode — new Plugin API format with tool.execute hooks
• Gemini CLI — added AfterAgent/AfterModel hooks for response capture
• Cursor — conversation_id-based session routing, afterAgentResponse capture

Event enrichment

• Every event in events.jsonl now carries _ts (timestamp), _hook (lifecycle type), _turn (boundary marker)
• Enables session replay with real-time pacing

Supports:

• Claude Code
• Gemini CLI
• Cursor
• OpenCode
• Codex (via native notify hook)

Install

npm install -g @claudemini/ses-cli

Or run without installing:

npx @claudemini/ses-cli <command>

Node requirement: >= 18

Quick Start

cd /path/to/your/project
ses enable          # Enable for Claude Code (default)
ses enable --all    # Enable for all supported agents
ses enable codex    # Enable for Codex (configures ~/.codex/config.toml)

Then use your AI agent normally. Session data is captured automatically.

ses status          # Current session
ses list            # All sessions
ses view <id>       # Session details (accepts session ID or shadow branch name)

Platform Setup

Claude Code / Gemini CLI / Cursor / OpenCode

ses enable --all

Installs hooks in .claude/settings.json, .gemini/settings.json, .cursor/hooks.json, .opencode/plugins/ses.ts.

Codex

ses enable codex

Automatically adds notify = ["ses", "codex-notify"] to ~/.codex/config.toml. Zero daemon, zero background process.

Disable

ses disable              # Remove project hooks (keeps Codex global config)
ses disable --global     # Also remove Codex global config
ses disable --clean      # Remove all data

Core Commands

Session Tracking

ses status
ses list
ses view <session-id>
ses view <shadow-branch>         # e.g. ses view ses/4b3a871
ses view <session-id> --json
ses query --recent=5
ses query --file=src/auth.ts
ses explain <session-id>

Review

ses review
ses review --json
ses review --md
ses review --recent=3
ses review --engine=multi-agent --providers=codex,dim,opencode
ses review --strict --fail-on=medium

Checkpoints

ses checkpoints
ses commit
ses shadow               # List shadow branches
ses rewind <checkpoint>
ses resume <checkpoint>
ses reset --force

Maintenance

ses doctor
ses doctor --fix
ses clean --days=7 --dry-run
ses clean --days=7
ses summarize <session-id>
ses webhook
ses webhook --test
ses pricing status
ses pricing sync

What It Writes

.ses-logs/
  .gitignore              # Ignores all contents
  index.json
  <session-id>/
    events.jsonl          # Raw events with _ts, _hook, _turn
    state.json            # Session state (tools, files, turns, tokens)
    review.json
    review-run.json
    review.md

.git/ses-sessions/        # V2 state (source of truth)
  <session-id>.json

ses/<commit>              # Shadow branch: full working tree snapshot
ses/committed/v1          # Committed branch: checkpoint metadata
  <shard>/0/
    metadata.json
    full.jsonl            # Agent transcript
    context.md            # Conversation (prompt + response per turn)
    prompt.txt
    content_hash.txt

Configuration

Configuration lives in .ses-logs/config.json. Environment variables override config file values.

Pricing example:

{
  "pricing": {
    "models": {
      "claude-sonnet-4": {
        "match": "prefix",
        "input_per_million": 3.0,
        "output_per_million": 15.0,
        "cache_read_input_per_million": 0.3,
        "cache_creation_input_per_million": 3.75
      }
    }
  }
}

Webhook example:

{
  "webhooks": {
    "url": "https://example.com/hook",
    "events": ["session.ended", "review.completed"],
    "secret": "",
    "auth_token": ""
  }
}

Publish

npm run lint
npm run typecheck
npm test
npm pack --dry-run
npm publish --access public

License

See package.json.