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. Think of it as a black box flight recorder for AI-assisted development.

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        AI Coding Agents                             │
│   Claude Code   Gemini CLI    Cursor    OpenCode    Codex           │
│       │              │           │          │          │            │
│    hooks.json    settings.json  hooks.json  plugin.ts  notify       │
└───────┬──────────────┬───────────┬──────────┬──────────┬────────────┘
        │              │           │          │          │
        └──────────────┴───────────┴──────────┴──────────┘
                                   │
                          ┌────────▼────────┐
                          │   ses log <evt>  │  Unified entry point
                          └────────┬────────┘
                                   │
                    ┌──────────────▼──────────────┐
                    │    dispatchHookEvent()       │
                    │                              │
                    │  1. Validate & parse         │
                    │  2. Enrich (_ts, _hook)      │
                    │  3. Append events.jsonl      │
                    │  4. Update V2 state          │
                    │     - prompts, turns         │
                    │     - tool_counts, file_ops  │
                    │     - token_usage, errors    │
                    │  5. Phase machine → actions  │
                    │  6. Save state               │
                    │  7. Write state.json (compat)│
                    │  8. Enqueue outbox           │
                    └──┬──────────────────────┬────┘
                       │                      │
              ┌────────▼──┐           ┌───────▼────────┐
              │ Checkpoint │           │ Outbox/Webhook │
              │            │           │                │
              │ SaveStep   │           │ batch upload   │
              │ Condense   │           │ session.ended  │
              └─────┬──────┘           └────────────────┘
                    │
           ┌────────▼──────────────┐
           │  Git Branches          │
           │                        │
           │  ses/<commit>          │  Shadow: full working tree
           │  ses/blackbox/v1       │  Blackbox: metadata + transcript
           └────────────────────────┘

Data Flow

Hook event (JSON)
  │
  ├─► events.jsonl          Append-only event log with timestamps
  │                         Every event: { ..., _ts, _hook, _turn }
  │
  ├─► V2 SessionState       Single source of truth
  │   (.git/ses-sessions/)   Prompts, turns, tools, tokens, files, phase
  │
  ├─► state.json            Backward-compatible projection
  │   (.ses-logs/<id>/)      Read by: ses view, ses list, review, overview
  │
  ├─► outbox.jsonl           Queued for service delivery
  │   (.ses-logs/.reporting/) Batched upload (50 events/batch)
  │
  ├─► Shadow branch          Full working tree snapshot per turn
  │   (ses/<commit-hash>)    Restorable: git checkout ses/<hash>
  │
  └─► Blackbox branch        Persistent metadata on orphan branch
      (ses/blackbox/v1)      Sharded: <id[:2]>/<id[2:]>/0/
                             Files: metadata.json, full.jsonl,
                                    context.md, prompt.txt

Turn Lifecycle

UserPromptSubmit ──► TurnStart ──► prompt recorded
                                        │
                     PreToolUse  ◄──────┤ (Read, Edit, Bash, ...)
                     PostToolUse ◄──────┤ tool_counts++, file_ops updated
                     PreToolUse  ◄──────┤
                     PostToolUse ◄──────┘
                                        │
Stop / AfterAgent ──► TurnEnd ───► turn paired (prompt + response)
                                        │
                     SaveStep ───► shadow branch checkpoint (dedup by tree hash)

Platform Integration

┌─────────────┬──────────────────────┬──────────────────────────────────┐
│ Agent       │ Hook mechanism       │ Data captured                    │
├─────────────┼──────────────────────┼──────────────────────────────────┤
│ Claude Code │ .claude/settings.json│ Prompt, response, tools, tokens  │
│             │ (hook commands)      │ last_assistant_message via Stop   │
├─────────────┼──────────────────────┼──────────────────────────────────┤
│ Gemini CLI  │ .gemini/settings.json│ Prompt, response, tools, tokens  │
│             │ (matcher hooks)      │ prompt_response via AfterAgent   │
├─────────────┼──────────────────────┼──────────────────────────────────┤
│ Cursor      │ .cursor/hooks.json   │ Prompt, response, tools          │
│             │ (hook commands)      │ text via afterAgentResponse      │
├─────────────┼──────────────────────┼──────────────────────────────────┤
│ OpenCode    │ .opencode/plugins/   │ Prompt, response, tools, tokens  │
│             │ ses.ts (Plugin API)  │ message.part.updated (sync)      │
├─────────────┼──────────────────────┼──────────────────────────────────┤
│ Codex       │ ~/.codex/config.toml │ Prompt, response (per turn)      │
│             │ notify = ["ses", ..] │ Zero daemon, native notify hook  │
└─────────────┴──────────────────────┴──────────────────────────────────┘

Release 1.8.0

Checkpoint system aligned with Entire CLI

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

Unified state system

• Single V2 pipeline replaces dual V2/legacy system
• Tool tracking (tool_counts, file_ops, errors) merged into SessionStateV2
• Turn pairing happens immediately on AI response
• files_touched derived from actual tool operations

5-platform data collection

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

Event enrichment

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

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)

Platform Setup

Claude Code / Gemini CLI / Cursor / OpenCode

ses enable --all

Codex

ses enable codex

Adds notify = ["ses", "codex-notify"] to ~/.codex/config.toml. Zero daemon.

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 --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.md

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

ses/<commit>              # Shadow branch: full working tree snapshot
ses/blackbox/v1           # Blackbox branch: checkpoint metadata
  <shard>/0/
    metadata.json         # Session & checkpoint info
    full.jsonl            # Agent transcript (complete)
    context.md            # Conversation (prompt + response per turn)
    prompt.txt            # User prompts
    content_hash.txt      # Dedup hash

Configuration

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

Pricing:

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

Webhooks:

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