agent-session-search
npx skills add https://github.com/oakoss/agent-skills --skill agent-session-search
Agent 安装分布
Skill 文档
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