cass

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

# Find the current session for this workspace
cass sessions --current --json

# List recent sessions for a specific project
cass sessions --workspace "$(pwd)" --json --limit 5

# Common agent flow: find current session, then export it
cass export-html "$(cass sessions --current --json | jq -r '.sessions[0].path')" --json

# 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:

1. Discovers SSH hosts from ~/.ssh/config
2. Probes each for agent data and cass installation
3. Optionally installs cass on remotes
4. Indexes sessions on remotes
5. Configures sources.toml
6. 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/cass/sources.toml (macOS).

---

Robot Mode Deep Dive

Self-Documenting API

CASS teaches agents how to use itself:

# Quick capability check
cass capabilities --json
# Returns: features, connectors, limits

# Full API schema
cass introspect --json
# Returns: all commands, arguments, response shapes

# Topic-based docs (LLM-optimized)
cass robot-docs commands   # all commands and flags
cass robot-docs schemas    # response JSON schemas
cass robot-docs examples   # copy-paste invocations
cass robot-docs exit-codes # error handling
cass robot-docs guide      # quick-start walkthrough
cass robot-docs contracts  # API versioning
cass robot-docs sources    # remote sources guide

Forgiving Syntax (Agent-Friendly)

CASS auto-corrects common mistakes:

What you type	What CASS understands
cass serach "error"	cass search "error" (typo corrected)
cass -robot -limit=5	cass --robot --limit=5 (single-dash fixed)
cass --Robot --LIMIT 5	cass --robot --limit 5 (case normalized)
cass find "auth"	cass search "auth" (alias resolved)
cass --limt 5	cass --limit 5 (Levenshtein <=2)

Command Aliases:

• find, query, q, lookup, grep → search
• ls, list, info, summary → stats
• st, state → status
• reindex, idx, rebuild → index
• show, get, read → view
• docs, help-robot, robotdocs → robot-docs

Output Formats

# Pretty-printed JSON (default)
cass search "error" --robot

# Streaming JSONL (header + one hit per line)
cass search "error" --robot-format jsonl

# Compact single-line JSON
cass

---

*Content truncated.*