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

Supports:

• Claude Code
• Gemini CLI
• Cursor
• OpenCode

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

# use your agent normally

ses status
ses list
ses view <session-id>

Enable all supported agents:

ses enable --all

Enable commit-time checkpoints too:

ses enable --checkpoint

Core Commands

Setup

ses enable
ses enable --all
ses enable --checkpoint
ses disable
ses disable --clean

Session Tracking

ses status
ses list
ses view <session-id>
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

Review options:

• --engine=<agent|multi-agent>
• --providers=<claude|codex|qwen|dim|opencode>[,...]
• --recent=<n>
• --all
• --min-severity=<info|low|medium|high|critical>
• --fail-on=<info|low|medium|high|critical>
• --provider-timeout-ms=<ms>
• --max-provider-parallelism=<n>
• --agent-timeout-ms=<ms>
• --allow-worktree-diff
• --agent-auto-approve=<bool>
• --no-agent-auto-approve
• --strict
• --strict-contract
• --json
• --markdown / --md

Checkpoints

ses checkpoints
ses commit
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

What It Writes

Session data is stored under:

.ses-logs/
  index.json
  <session-id>/
    events.jsonl
    state.json
    summary.json
    metadata.json
    summary.txt
    context.md
    prompts.txt
    review.json
    review-run.json
    review.md

These artifacts are designed to be both human-readable and machine-consumable.

Configuration

Configuration lives in:

.ses-logs/config.json

Environment variables override config file values.

Minimal OpenAI-compatible example:

{
  "provider": "openai",
  "api_key": "sk-...",
  "model": "gpt-4o-mini",
  "openai_base_url": "https://api.openai.com/v1"
}

Minimal Anthropic example:

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

Webhook example:

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

Relevant environment variables:

• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• OPENAI_BASE_URL
• OPENAI_ENDPOINT
• OPENAI_MODEL
• ANTHROPIC_MODEL
• AI_MODEL
• SES_WEBHOOK_URL
• SES_WEBHOOK_SECRET
• SES_WEBHOOK_AUTH_TOKEN
• SES_WEBHOOK_EVENTS

Publish Notes

This package publishes compiled output, not source files.

Current release flow:

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

License

See package.json.