@claudemini/shit-cli

shit-cli

Session-based Hook Intelligence Tracker

A zero-dependency 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

npm install -g @claudemini/shit-cli

cd /path/to/your/project
shit enable          # Setup hooks + .shit-logs
# ... use Claude Code normally ...
shit list            # See sessions
shit status          # Check current session

Installation

npm install -g @claudemini/shit-cli

Or use directly without installing:

npx @claudemini/shit-cli <command>

Commands

Setup

shit enable                    # Enable for Claude Code (default)
shit enable gemini-cli         # Enable for Gemini CLI
shit enable --all              # Enable for all supported agents
shit enable --checkpoint       # Also create checkpoints on git commit
shit disable                   # Remove hooks (keep data)
shit disable --clean           # Remove hooks and all data
shit init                      # Low-level: register hooks in .claude/settings.json

Session Tracking

shit status                    # Show current session + git info
shit list                      # List all sessions with type, risk, intent
shit view <session-id>         # View semantic session report
shit view <session-id> --json  # Include raw JSON data
shit review [session-id]       # Run structured code review from session data
shit review --json             # Machine-readable findings (structured schema)
shit review --recent=3 --md    # Aggregated Markdown report for PR comments
shit review --strict --fail-on=medium  # CI gate by severity threshold
shit explain <session-id>      # Human-friendly explanation of a session
shit explain <commit-sha>      # Explain a commit via its checkpoint

shit review options:

• --recent=<n> review latest n sessions (default 1)
• --all review all sessions in .shit-logs
• --min-severity=<info|low|medium|high|critical> filter findings
• --fail-on=<info|low|medium|high|critical> strict-mode failure threshold (default high)
• --strict exit code 1 when findings reach --fail-on
• --json output structured JSON
• --markdown / --md output Markdown

Cross-Session Queries

shit query --recent=5                         # Recent 5 sessions
shit query --file=src/auth/auth.service.ts    # Sessions that modified this file
shit query --type=bugfix                      # All bugfix sessions
shit query --risk=high                        # High-risk sessions
shit query --type=feature --json              # JSON output for bot consumption

Checkpoints & Recovery

shit checkpoints               # List all checkpoints
shit commit                    # Manually create checkpoint for current HEAD
shit rewind <checkpoint>       # Rollback to a checkpoint (git reset --hard)
shit rewind --interactive      # Choose from available checkpoints
shit resume <checkpoint>       # Restore session data from a checkpoint
shit reset --force             # Delete checkpoint for current HEAD

Maintenance

shit doctor                    # Diagnose issues (corrupted state, stuck sessions)
shit doctor --fix              # Auto-fix detected issues
shit shadow                    # List shadow branches
shit shadow info <branch>      # Show branch details
shit clean --days=7 --dry-run  # Preview cleanup
shit clean --days=7            # Delete sessions older than 7 days
shit summarize <session-id>    # Generate AI summary (requires API key)

Command Reference

Command	Description
enable	Enable shit-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 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 (.shit-logs/ + index.json)
              |
         Code Review Bot / Human Queries

• 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 (bot-readable), summary.txt (human-readable), context.md, metadata.json, and prompts.txt are regenerated on every event.
• Checkpoints - On session end or git commit, session data is committed to an orphan git branch using plumbing commands (no working tree impact).

Data Model

Session Directory

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

{
  "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('.shit-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('.shit-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

shit-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	shit review finishes	Review report

Configuration

Add a webhooks field to .shit-logs/config.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
  }
}

Or use environment variables (higher priority than config.json):

export SHIT_WEBHOOK_URL=https://example.com/hook
export SHIT_WEBHOOK_SECRET=my-secret        # HMAC-SHA256 signing
export SHIT_WEBHOOK_AUTH_TOKEN=bearer-token  # Bearer auth (alternative to secret)
export SHIT_WEBHOOK_EVENTS=session.ended,review.completed

Authentication

• HMAC-SHA256 — Set secret or SHIT_WEBHOOK_SECRET. Adds X-Signature-256: sha256=<hex> header (GitHub-compatible format).
• Bearer token — Set auth_token or SHIT_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

shit webhook              # Show current webhook configuration
shit 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 ANTHROPIC_API_KEY=sk-...   # Uses claude-3-haiku by default

Then run:

shit summarize <session-id>

Environment Variables

Variable	Description
SHIT_LOG_DIR	Custom log directory (default: .shit-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)
ANTHROPIC_API_KEY	Enable AI summaries via Anthropic
SHIT_WEBHOOK_URL	Webhook endpoint URL
SHIT_WEBHOOK_SECRET	HMAC-SHA256 signing secret for webhooks
SHIT_WEBHOOK_AUTH_TOKEN	Bearer token for webhook authentication
SHIT_WEBHOOK_EVENTS	Comma-separated list of webhook events to subscribe to

Security

• Session logs are stored locally in .shit-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

License

MIT