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