Agent Session Search
Unified CLI/TUI to index and search local coding agent history. Aggregates sessions from 13+ agents into a single searchable index with sub-60ms latency. Purpose-built for AI agent consumption with robot mode and forgiving syntax. Not a library -- CASS is an external Rust CLI that must be installed separately.
Do not use for real-time session monitoring. Do not use when the agent has no local session history stored on disk.
Install via curl one-liner, Homebrew, or Scoop (see Configuration reference). Requires Rust nightly toolchain for building from source.
CRITICAL: NEVER run bare cass -- it launches an interactive TUI that blocks your session. Always use --robot or --json flags.
Essential Commands
| Command |
Purpose |
cass health --json |
Health check (exit 0 = healthy, non-zero = unhealthy) |
cass index --full |
Full rebuild of DB and search index |
cass index |
Incremental update since last scan |
cass index --watch |
Watch mode: auto-reindex on file changes |
cass search "query" --robot |
Search with JSON output |
cass search "query" --robot --fields minimal |
Minimal payload (path, line, agent) |
cass search "query" --robot --limit 5 |
Cap number of results |
cass search "query" --robot --mode hybrid |
Use hybrid (lexical + semantic) search |
cass view /path -n 42 --json |
View source at specific line |
cass expand /path -n 42 -C 5 --json |
Context around a search result |
cass export-html /path |
Export conversation as self-contained HTML |
cass robot-docs guide |
LLM-optimized documentation |
cass robot-docs schemas |
Response JSON schemas |
cass sources setup |
Configure multi-machine remote sources |
Supported Agents
| Agent |
Location |
Format |
| Claude Code |
~/.claude/projects |
JSONL |
| Codex |
~/.codex/sessions |
Rollout JSONL |
| Gemini CLI |
~/.gemini/tmp |
JSON |
| Cline |
VS Code global storage |
Task directories |
| OpenCode |
.opencode directories |
SQLite |
| Amp |
~/.local/share/amp + VS Code |
Mixed |
| Cursor |
~/Library/Application Support/Cursor/User/ |
SQLite state.vscdb |
| ChatGPT |
~/Library/Application Support/com.openai.chat |
JSON (v1 unencrypted; v2/v3 encrypted) |
| Aider |
~/.aider.chat.history.md + per-project |
Markdown |
| Pi-Agent |
~/.pi/agent/sessions |
JSONL |
| Factory (Droid) |
~/.factory/sessions |
JSONL |
| Clawdbot |
~/.clawdbot/sessions |
JSONL |
| Vibe (Mistral) |
~/.vibe/logs/session/*/messages.jsonl |
JSONL |
Search Modes
| Mode |
Algorithm |
Best For |
| lexical (default) |
BM25 full-text via Tantivy |
Exact term matching, code searches |
| semantic |
Vector similarity (MiniLM via FastEmbed) |
Conceptual queries, finding similar |
| hybrid |
Reciprocal Rank Fusion (RRF) |
Balanced precision and recall |
Semantic mode requires MiniLM model files. When unavailable, CASS falls back to a hash-based embedder for approximate similarity.
Forgiving Syntax
CASS auto-corrects common agent mistakes and emits teaching notes to stderr:
| Input |
Correction |
| Typos in commands |
Levenshtein-matched to canonical command |
Single-dash long flags (-robot) |
Normalized to --robot |
Wrong case (--Robot) |
Lowercased to --robot |
Common Mistakes
| Mistake |
Fix |
Running bare cass |
Always use --robot or --json |
Missing --robot flag |
Add --robot for JSON output |
| No index exists |
Run cass index --full first |
| Token budget overflow |
Use --fields minimal and --limit |
| Stale search results |
Run cass index to refresh |
| Parsing stderr as JSON |
stdout = JSON only, diagnostics go to stderr |
| Assuming CASS is installed |
Check cass health --json first |
Delegation
Use this skill for indexing, searching, and analyzing coding agent session history via CASS CLI. Delegates to the external cass binary for all operations. Run cass robot-docs guide for the authoritative command reference directly from the installed version.
For multi-machine session search, see Remote Sources. For TUI usage by human operators, see TUI Reference.
References
- Command Reference -- indexing, search, session viewing, export, and diagnostics
- Robot Mode -- self-documenting API, forgiving syntax, output formats, token budget
- Query Language -- boolean operators, wildcards, match types, time formats, auto-fuzzy fallback
- Search and Ranking -- search modes, ranking, scoring formula
- Remote Sources -- multi-machine search via SSH/rsync, setup wizard, path mappings
- TUI Reference -- keyboard shortcuts, themes, saved views, density modes, bookmarks
- Error Handling -- structured errors, exit codes, troubleshooting
- Internals -- response shapes, deduplication, performance, watch mode, semantic search
- Configuration -- environment variables, shell completions, installation, integrations
1---2name: agent-session-search3description: Coding Agent Session Search - unified CLI/TUI to index and search local coding agent history from Claude Code, Codex, Gemini, Cursor, Aider, ChatGPT, Cline, OpenCode, Amp, Pi-Agent, Factory, and more. Use when searching past agent conversations, indexing coding session history, finding previous solutions across agents, or querying session logs with CASS CLI robot mode.4license: MIT5---6
7# Agent Session Search
8
9Unified CLI/TUI to index and search local coding agent history. Aggregates sessions from 13+ agents into a single searchable index with sub-60ms latency. Purpose-built for AI agent consumption with robot mode and forgiving syntax. Not a library -- CASS is an external Rust CLI that must be installed separately.
10
11Do not use for real-time session monitoring. Do not use when the agent has no local session history stored on disk.
12
13Install via `curl` one-liner, Homebrew, or Scoop (see Configuration reference). Requires Rust nightly toolchain for building from source.
14
15**CRITICAL: NEVER run bare `cass` -- it launches an interactive TUI that blocks your session. Always use `--robot` or `--json` flags.**
16
17## Essential Commands
18
19| Command | Purpose |
20| ---------------------------------------------- | ----------------------------------------------------- |
21| `cass health --json` | Health check (exit 0 = healthy, non-zero = unhealthy) |
22| `cass index --full` | Full rebuild of DB and search index |
23| `cass index` | Incremental update since last scan |
24| `cass index --watch` | Watch mode: auto-reindex on file changes |
25| `cass search "query" --robot` | Search with JSON output |
26| `cass search "query" --robot --fields minimal` | Minimal payload (path, line, agent) |
27| `cass search "query" --robot --limit 5` | Cap number of results |
28| `cass search "query" --robot --mode hybrid` | Use hybrid (lexical + semantic) search |
29| `cass view /path -n 42 --json` | View source at specific line |
30| `cass expand /path -n 42 -C 5 --json` | Context around a search result |
31| `cass export-html /path` | Export conversation as self-contained HTML |
32| `cass robot-docs guide` | LLM-optimized documentation |
33| `cass robot-docs schemas` | Response JSON schemas |
34| `cass sources setup` | Configure multi-machine remote sources |
35
36## Supported Agents
37
38| Agent | Location | Format |
39| --------------- | ----------------------------------------------- | -------------------------------------- |
40| Claude Code | `~/.claude/projects` | JSONL |
41| Codex | `~/.codex/sessions` | Rollout JSONL |
42| Gemini CLI | `~/.gemini/tmp` | JSON |
43| Cline | VS Code global storage | Task directories |
44| OpenCode | `.opencode` directories | SQLite |
45| Amp | `~/.local/share/amp` + VS Code | Mixed |
46| Cursor | `~/Library/Application Support/Cursor/User/` | SQLite state.vscdb |
47| ChatGPT | `~/Library/Application Support/com.openai.chat` | JSON (v1 unencrypted; v2/v3 encrypted) |
48| Aider | `~/.aider.chat.history.md` + per-project | Markdown |
49| Pi-Agent | `~/.pi/agent/sessions` | JSONL |
50| Factory (Droid) | `~/.factory/sessions` | JSONL |
51| Clawdbot | `~/.clawdbot/sessions` | JSONL |
52| Vibe (Mistral) | `~/.vibe/logs/session/*/messages.jsonl` | JSONL |
53
54## Search Modes
55
56| Mode | Algorithm | Best For |
57| ----------------- | ---------------------------------------- | ----------------------------------- |
58| lexical (default) | BM25 full-text via Tantivy | Exact term matching, code searches |
59| semantic | Vector similarity (MiniLM via FastEmbed) | Conceptual queries, finding similar |
60| hybrid | Reciprocal Rank Fusion (RRF) | Balanced precision and recall |
61
62Semantic mode requires MiniLM model files. When unavailable, CASS falls back to a hash-based embedder for approximate similarity.
63
64## Forgiving Syntax
65
66CASS auto-corrects common agent mistakes and emits teaching notes to stderr:
67
68| Input | Correction |
69| --------------------------------- | ---------------------------------------- |
70| Typos in commands | Levenshtein-matched to canonical command |
71| Single-dash long flags (`-robot`) | Normalized to `--robot` |
72| Wrong case (`--Robot`) | Lowercased to `--robot` |
73
74## Common Mistakes
75
76| Mistake | Fix |
77| -------------------------- | -------------------------------------------- |
78| Running bare `cass` | Always use `--robot` or `--json` |
79| Missing `--robot` flag | Add `--robot` for JSON output |
80| No index exists | Run `cass index --full` first |
81| Token budget overflow | Use `--fields minimal` and `--limit` |
82| Stale search results | Run `cass index` to refresh |
83| Parsing stderr as JSON | stdout = JSON only, diagnostics go to stderr |
84| Assuming CASS is installed | Check `cass health --json` first |
85
86## Delegation
87
88Use this skill for indexing, searching, and analyzing coding agent session history via CASS CLI. Delegates to the external `cass` binary for all operations. Run `cass robot-docs guide` for the authoritative command reference directly from the installed version.
89
90For multi-machine session search, see Remote Sources. For TUI usage by human operators, see TUI Reference.
91
92## References
93
94- [Command Reference](references/command-reference.md) -- indexing, search, session viewing, export, and diagnostics
95- [Robot Mode](references/robot-mode.md) -- self-documenting API, forgiving syntax, output formats, token budget
96- [Query Language](references/query-language.md) -- boolean operators, wildcards, match types, time formats, auto-fuzzy fallback
97- [Search and Ranking](references/search-and-ranking.md) -- search modes, ranking, scoring formula
98- [Remote Sources](references/remote-sources.md) -- multi-machine search via SSH/rsync, setup wizard, path mappings
99- [TUI Reference](references/tui-reference.md) -- keyboard shortcuts, themes, saved views, density modes, bookmarks
100- [Error Handling](references/error-handling.md) -- structured errors, exit codes, troubleshooting
101- [Internals](references/internals.md) -- response shapes, deduplication, performance, watch mode, semantic search
102- [Configuration](references/configuration.md) -- environment variables, shell completions, installation, integrations
oakoss