@cluademini/shit-cli

shit-cli

Session-based Hook Intelligence Tracker

A memory system for human-AI interactions, designed to provide reliable data support for code review automation.

Design Vision

• Human-AI Interaction Memory System - Long-term memory, not temporary logs
• Code Review Bot Data Support - Structured semantic data for intelligent code review

See DESIGN_PHILOSOPHY.md for detailed design rationale.

Installation

cd shit-cli
npm link

Or use directly:

node bin/shit.js <command>

Usage

Initialize hooks

cd /path/to/your/project
shit init

Registers all hooks in .claude/settings.json automatically.

List sessions

shit list

Output:

3 session(s):

1. f608c31e  [bugfix]  risk:medium
   Fix auth timeout by adjusting retry logic
   45min | 42 events | 28 tools | 3 files | 0 errors
   2/27/2026, 3:15:00 PM

2. a1b2c3d4  [feature]  risk:low
   Add user profile endpoint
   30min | 28 events | 15 tools | 2 files | 0 errors
   2/26/2026, 10:30:00 AM

View session details

shit view f608c31e-453c-435a-b0e2-3116dc56ad71
shit view f608c31e-453c-435a-b0e2-3116dc56ad71 --json  # Include raw JSON

Output includes: intent, changes by category, tools, commands, review hints (tests run, build verified, config changed, etc.).

Query session memory

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

Shadow branches

shit shadow                     # List shadow branches
shit shadow info <branch>       # Show branch details

Clean old sessions

shit clean --days=7 --dry-run   # Preview
shit clean --days=7             # Delete sessions older than 7 days

Commands

Command	Description
init	Initialize hooks in .claude/settings.json
log <hook-type>	Log a hook event from stdin (called by hooks)
list	List all sessions with type, intent, risk
view <session-id> [--json]	View semantic session report
query [options]	Query session memory across sessions
shadow [info <branch>]	List or inspect shadow branches
clean [--days=N] [--dry-run]	Clean old sessions
help	Show help

Architecture

shit-cli/
├── bin/shit.js              # CLI entry point
├── lib/
│   ├── config.js            # Shared config: getProjectRoot(), getLogDir(), toRelative()
│   ├── extract.js           # Semantic extraction: intent, changes, classification
│   ├── report.js            # Report generation: summary.json v2, summary.txt, metadata
│   ├── session.js           # Session state management + cross-session index
│   ├── log.js               # Event ingestion dispatcher (stdin → parse → extract → save)
│   ├── init.js              # shit init (hook registration)
│   ├── list.js              # shit list (semantic session listing)
│   ├── view.js              # shit view (semantic report display)
│   ├── query.js             # shit query (cross-session memory queries)
│   ├── clean.js             # shit clean (session cleanup)
│   ├── shadow.js            # shit shadow (branch listing)
│   └── git-shadow.js        # Git plumbing for shadow branches

Data Model

Session Directory

.shit-logs/
├── index.json                              # Cross-session index (file history, types)
└── <session-id>/
    ├── events.jsonl                        # Raw hook events
    ├── state.json                          # Incremental processing state
    ├── summary.json                        # Bot data interface (v2 schema)
    ├── summary.txt                         # Human-readable semantic report
    ├── prompts.txt                         # User prompts with timestamps
    └── metadata.json                       # Lightweight session metadata

summary.json v2 Schema

{
  "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/auth.service.ts",
      "category": "source",
      "operations": ["edit"],
      "editCount": 2,
      "editSummary": "Modified timeout logic"
    }],
    "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/auth.service.ts"],
    "large_change": false,
    "config_changed": false,
    "migration_added": false
  },
  "prompts": ["Fix the auth timeout bug", "Run the tests"],
  "scope": ["auth"]
}

Cross-Session Index

{
  "project": "my-project",
  "sessions": [{
    "id": "f608c31e...",
    "date": "2026-02-27",
    "type": "bugfix",
    "intent": "Fix auth timeout",
    "files": ["src/auth/auth.service.ts"],
    "duration": 45,
    "risk": "medium"
  }],
  "file_history": {
    "src/auth/auth.service.ts": ["f608c31e...", "a1b2c3d4..."]
  }
}

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
unknown	Unclassified

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

// Read session data
const summary = JSON.parse(fs.readFileSync('.shit-logs/<id>/summary.json'));

// 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(fs.readFileSync('.shit-logs/index.json'));
const history = index.file_history['src/auth/auth.service.ts'];
if (history.length > 3) {
  review.note('This file has been modified frequently');
}

Environment Variables

• SHIT_LOG_DIR: Custom log directory (default: ./.shit-logs in project root)

License

MIT