CASS - Coding Agent Session Search
Unified, high-performance CLI/TUI to index and search your local coding agent history. Aggregates sessions from 11 agents: Codex, Claude Code, Gemini CLI, Cline, OpenCode, Amp, Cursor, ChatGPT, Aider, Pi-Agent, and Factory (Droid).
CRITICAL: Robot Mode Required for AI Agents
NEVER run bare cass - it launches an interactive TUI that blocks your session!
# WRONG - blocks terminal
cass
# CORRECT - JSON output for agents
cass search "query" --robot
cass search "query" --json # alias
Always use --robot or --json flags for machine-readable output.
Quick Reference for AI Agents
Pre-Flight Check
# Health check (exit 0=healthy, 1=unhealthy, <50ms)
cass health
# If unhealthy, rebuild index
cass index --full
Essential Commands
# Search with JSON output
cass search "authentication error" --robot --limit 5
# Search with metadata (elapsed_ms, cache stats, freshness)
cass search "error" --robot --robot-meta
# Minimal payload (path, line, agent only)
cass search "bug" --robot --fields minimal
# View source at specific line
cass view /path/to/session.jsonl -n 42 --json
# Expand context around a line
cass expand /path/to/session.jsonl -n 42 -C 5 --json
# Capabilities discovery
cass capabilities --json
# Full API schema
cass introspect --json
# LLM-optimized documentation
cass robot-docs guide
cass robot-docs commands
cass robot-docs schemas
cass robot-docs examples
cass robot-docs exit-codes
Why Use CASS
Cross-Agent Knowledge Transfer
Your coding agents create scattered knowledge:
- Claude Code sessions in
~/.claude/projects - Codex sessions in
~/.codex/sessions - Cursor state in SQLite databases
- Aider history in markdown files
CASS unifies all of this into a single searchable index. When you're stuck on a problem, search across ALL your past agent sessions to find relevant solutions.
Use Cases
# "I solved this before..."
cass search "TypeError: Cannot read property" --robot --days 30
# Cross-agent learning (what has ANY agent said about X?)
cass search "authentication" --robot --workspace /path/to/project
# Agent-to-agent handoff
cass search "database migration" --robot --fields summary
# Daily review
cass timeline --today --json
Command Reference
Indexing
# Full rebuild of DB and search index
cass index --full
# Incremental update (since last scan)
cass index
# Watch mode: auto-reindex on file changes
cass index --watch
# Force rebuild even if schema unchanged
cass index --full --force-rebuild
# Safe retries with idempotency key (24h TTL)
cass index --full --idempotency-key "build-$(date +%Y%m%d)"
# JSON output with stats
cass index --full --json
Search
# Basic search (JSON output required for agents!)
cass search "query" --robot
# With filters
cass search "error" --robot --agent claude --days 7
cass search "bug" --robot --workspace /path/to/project
cass search "panic" --robot --today
# Time filters
cass search "auth" --robot --since 2024-01-01 --until 2024-01-31
cass search "test" --robot --yesterday
cass search "fix" --robot --week
# Wildcards
cass search "auth*" --robot # prefix: authentication, authorize
cass search "*tion" --robot # suffix: authentication, exception
cass search "*config*" --robot # substring: misconfigured
# Token budget management (critical for LLMs!)
cass search "error" --robot --fields minimal # path, line, agent only
cass search "error" --robot --fields summary # adds title, score
cass search "error" --robot --max-content-length 500 # truncate fields
cass search "error" --robot --max-tokens 2000 # soft budget (~4 chars/token)
cass search "error" --robot --limit 5 # cap results
# Pagination (cursor-based)
cass search "TODO" --robot --robot-meta --limit 20
# Use _meta.next_cursor from response:
cass search "TODO" --robot --robot-meta --limit 20 --cursor "eyJ..."
# Match highlighting
cass search "authentication error" --robot --highlight
# Query analysis/debugging
cass search "auth*" --robot --explain # parsed query, cost estimates
cass search "auth error" --robot --dry-run # validate without executing
# Aggregations (server-side counts)
cass search "error" --robot --aggregate agent,workspace,date
# Request correlation
cass search "bug" --robot --request-id "req-12345"
# Source filtering (for multi-machine setups)
cass search "auth" --robot --source laptop
cass search "error" --robot --source remote
# Traceability (for debugging agent pipelines)
cass search "error" --robot --trace-file /tmp/cass-trace.json
Session Analysis
# Export conversation to markdown/HTML/JSON
cass export /path/to/session.jsonl --format markdown -o conversation.md
cass export /path/to/session.jsonl --format html -o conversation.html
cass export /path/to/session.jsonl --format json --include-tools
# Expand context around a line (from search result)
cass expand /path/to/session.jsonl -n 42 -C 5 --json
# Shows 5 messages before and after line 42
# View source at line
cass view /path/to/session.jsonl -n 42 --json
# Activity timeline
cass timeline --today --json --group-by hour
cass timeline --days 7 --json --agent claude
cass timeline --since 7d --json
# Find related sessions for a file
cass context /path/to/source.ts --json
Status & Diagnostics
# Quick health (<50ms)
cass health
cass health --json
# Full status snapshot
cass status --json
cass state --json # alias
# Statistics
cass stats --json
cass stats --by-source # for multi-machine
# Full diagnostics
cass diag --verbose
Aggregation & Analytics
Aggregate search results server-side to get counts and distributions without transferring full result data:
# Count results by agent
cass search "error" --robot --aggregate agent
# → { "aggregations": { "agent": { "buckets": [{"key": "claude_code", "count": 45}, ...] } } }
# Multi-field aggregation
cass search "bug" --robot --aggregate agent,workspace,date
# Combine with filters
cass search "TODO" --agent claude --robot --aggregate workspace
| Aggregation Field | Description |
|---|---|
agent | Group by agent type (claude_code, codex, cursor, etc.) |
workspace | Group by workspace/project path |
date | Group by date (YYYY-MM-DD) |
match_type | Group by match quality (exact, prefix, fuzzy) |
Top 10 buckets returned per field, with other_count for remaining items.
Remote Sources (Multi-Machine Search)
Search across sessions from multiple machines via SSH/rsync.
Setup Wizard (Recommended)
cass sources setup
The wizard:
- Discovers SSH hosts from
~/.ssh/config - Probes each for agent data and cass installation
- Optionally installs cass on remotes
- Indexes sessions on remotes
- Configures
sources.toml - Syncs data locally
cass sources setup --hosts css,csd,yto # Specific hosts only
cass sources setup --dry-run # Preview without changes
cass sources setup --resume # Resume interrupted setup
Manual Setup
# Add a remote machine
cass sources add user@laptop.local --preset macos-defaults
cass sources add dev@workstation --path ~/.claude/projects --path ~/.codex/sessions
# List sources
cass sources list --json
# Sync sessions
cass sources sync
cass sources sync --source laptop --verbose
# Check connectivity
cass sources doctor
cass sources doctor --source laptop --json
# Path mappings (rewrite remote paths to local)
cass sources mappings list laptop
cass sources mappings add laptop --from /home/user/projects --to /Users/me/projects
cass sources mappings test laptop /home/user/projects/myapp/src/main.rs
# Remove source
cass sources remove laptop --purge -y
Configuration stored in ~/.config/cass/sources.toml (Linux) or `~/Library/Application Support/