| name | cass |
| description | cass CLI session search across coding agents with JSON or robot output. Use when user needs session evidence, cross-agent search, handoff recovery, or transcript-backed claims. |
CASS
cass is raw session search. Use it when you need evidence, not distilled guidance.
Prerequisites
command -v cass
If missing, stop and tell the user:
brew install dicklesworthstone/tap/cass
Golden Rules
- Never run bare
cass in an agent context. It opens the TUI.
- Always use
--json or --robot for machine-readable output.
- Run a cheap health check before deep searches.
- Treat
cass as a tool boundary; do not merge its runtime assumptions into Lev core.
Fast Path
cass health --json || cass index --full --json
cass search "authentication timeout" --robot --limit 5 --fields minimal
Core Commands
Health and readiness
cass health --json
cass status --json
cass capabilities --json
cass introspect --json
Search
cass search "query" --robot --limit 5
cass search "query" --robot --fields minimal
cass search "query" --robot --workspace /path/to/project
cass search "query" --robot --days 30
Inspect specific results
cass view /path/to/session.jsonl -n 42 --json
cass expand /path/to/session.jsonl -n 42 -C 5 --json
Documentation for agents
cass robot-docs guide
cass robot-docs commands
cass robot-docs schemas
Recommended Workflow
1. Check health
cass health --json
If unhealthy:
cass index --full --json
2. Search narrowly
Prefer scoped searches:
cass search "database migration" --robot --workspace /abs/path --limit 5
3. Expand only the promising hits
Use view or expand after search rather than dumping large result sets.
When To Use cass vs cm
Use cass for:
- raw session evidence
- exact historical wording
- line-level follow-up after search
- cross-agent recovery during handoffs
Use cm for:
- distilled rules
- anti-pattern recall
- pre-task memory hydration
Anti-Patterns
- Running
cass without --json or --robot
- Pulling large unscoped result sets into context
- Treating search hits as validated guidance without inspection
- Using
cass as the project task tracker
Minimal Extraction Pattern
## CASS Evidence
- Query:
- Hits used:
- Key lines or summaries:
- Why they matter:
Keep this evidence summary in the current Lev artifact, not in ad hoc notes.
