CASS (Cross-Agent Session Search)

Search and retrieve content from past AI coding sessions.

When This Applies

| Signal | Action | |--------|--------| | "How did we do this before?" | cass search | | "Find past solutions" | cass search | | Looking for patterns | cass search | | View specific session | cass view | | Today's activity | cass timeline |

CRITICAL RULE

Always use --robot or --json. Never run bare cass.

Bare cass launches a TUI that will hang AI agents.

Search

# Basic search
cass search "query" --robot --limit 5

# Lean output (path, line, agent)
cass search "query" --robot --fields minimal

# With summary (title, score)
cass search "query" --robot --fields summary

# Token budget
cass search "query" --robot --max-tokens 2000

# Wildcard prefix
cass search "auth*" --robot

# Workspace-specific
cass search "query" --workspace "/path/to/project" --robot

View & Expand

# View full session
cass view /path/to/session.jsonl --json

# Expand specific line with context
cass expand /path -n 42 -C 3 --json

Timeline

# Today's sessions
cass timeline --today --json

# Last week
cass timeline --since 7d --json

# Recent activity
cass timeline --days 7 --json --limit 10

Export

cass export /path/session.jsonl --format markdown
cass export /path/session.jsonl --format json

Indexing

# If search returns nothing
cass index --full

# Health check
cass health

Output Formats

--robot-format jsonl     # Streaming line-delimited JSON
--robot-format compact   # Minimal output

Query Tips

| Query Type | Example | |------------|---------| | Exact phrase | "error handling" | | Wildcard | auth* | | Multiple terms | database migration | | Recent | Add --since 7d |

Quick Reference

cass search "query" --robot --limit 5      # Basic search
cass search "query" --robot --fields minimal   # Lean output
cass view /path.jsonl --json               # View session
cass expand /path -n 42 -C 3 --json        # Expand with context
cass timeline --today --json               # Today's activity
cass index --full                          # Rebuild index

When to Use CASS vs Other Tools

| Need | Use | |------|-----| | Past session content | CASS | | Learned patterns/rules | cass-memory (cm) | | Current codebase | Warp-Grep or Grep | | Web documentation | Exa | | Task graph | bv |

cass-search