Search across all local coding agent history (Claude Code, Codex, Cursor, Gemini, Aider, and more) using cass. Use when you need to find how a problem was solved before, recall context from prior sessions, or check what any agent has done in a project.
cass indexes conversations from every local coding agent into a single searchable corpus. Before solving a problem from scratch, check whether any agent has already solved something similar.
Never run bare cass -- it launches an interactive TUI. Always use --robot
or --json.
Do not use cass for general web search or documentation lookup. It only searches local agent session history.
Before your first search in a session, confirm the index is healthy:
cass health --json
Exit 0 means the index is fine. Non-zero means you should rebuild:
cass index --full
The core command:
cass search "<query>" --robot --limit 5
Queries support boolean operators (AND, OR, NOT / -), exact phrases
("like this"), and prefix wildcards (auth*). Default behaviour is AND
across terms.
| Flag | What it does |
|---|---|
--robot / --json | Machine-readable JSON (required) |
--limit N | Cap result count |
--fields minimal | Only source_path, line_number, agent -- saves tokens |
--fields summary | Adds title and score |
--agent NAME | Filter to one agent (claude, codex, cursor, etc.) |
--workspace PATH | Filter to a specific project directory |
--today / --week / --days N | Time filters |
--since DATE --until DATE | Date range (flexible formats: ISO, relative like -7d) |
--aggregate agent,workspace | Server-side counts instead of full results |
--max-tokens N | Soft token budget for output (~4 chars/token) |
--mode lexical|semantic|hybrid | Search mode (default: lexical) |
Search hits include source_path and line_number. To see the full context
around a hit:
cass view /path/to/session.jsonl -n 42 --json
cass expand /path/to/session.jsonl -n 42 -C 5 --json
expand gives you N messages of context either side of the hit.
When you need an overview rather than specific hits, aggregate server-side:
cass search "error" --json --aggregate agent
cass search "*" --json --aggregate agent,workspace,date
This returns counts per bucket and is dramatically cheaper in tokens than fetching full results.
Start broad, then narrow. A good pattern:
Broad search to see if anything relevant exists:
cass search "auth timeout" --robot --limit 3 --fields summary
Narrow by project or agent if you get too many results:
cass search "auth timeout" --robot --workspace /path/to/project --days 14
Expand context around the best hit:
cass expand /path/to/session.jsonl -n 42 -C 5 --json
Use --fields minimal when scanning and --fields summary or full output
when you have found something worth reading.
Semantic mode (--mode semantic) is useful when you are searching by concept
rather than exact terms -- e.g. "how to handle user login" rather than
"authentication". Hybrid mode combines both.
--robot or --json is set)Errors include structured JSON with code, message, hint, and retryable
fields. If retryable is true, try again; otherwise, follow the hint.
cass aggregates sessions from: Claude Code, Codex, Gemini CLI, Cline, OpenCode, Amp, Cursor, ChatGPT, Aider, Pi-Agent, and Factory (Droid). Each conversation is normalised into a common schema with agent, workspace, timestamps, and message content.
If you need more detail than this skill provides, cass can explain itself:
cass robot-docs guide # quickstart
cass robot-docs commands # full flag reference
cass robot-docs examples # copy-paste invocations
cass robot-docs schemas # JSON response shapes
cass capabilities --json # feature discovery