Coding Agent Session Search - unified CLI/TUI to index and search local coding agent history from Claude Code, Codex, Gemini, Cursor, Aider, ChatGPT, Pi-Agent, Factory, and more. Purpose-built for AI agent consumption with robot mode.

CASS Coding Agent Session Search Unified, high performance CLI/TUI to index and search your local coding agent history. Aggregates sessions from 23 agents , including Codex, Claude Code, Gemini CLI, Cline, OpenCode, Amp, Cursor, ChatGPT, Aider, Pi Agent, Factory (Droid), OpenHands, Antigravity, and Grok Build. CRITICAL: Robot Mode Required for AI Agents NEVER run bare cass it launches an interactive TUI that blocks your session! Always use robot or json flags for machine readable output. Quick Reference for AI Agents Bounded History Retrieval For a quick project history question, start with one scoped query. The flag set below is verified on cass 0.8.0; check cass version and cass search help once per installed version. If no maintenance is unsupported, stop and report the version mismatch; silently removing it permits maintenance. timeout is in milliseconds; max tokens is an approximate output budget, not a CPU or memory limit. Apply a caller side wall clock deadline as well (for example, GNU timeout 10s before the command). Exit 124 from that wrapper is an incomplete attempt; its interrupted stdout may not be valid JSON. In JSON search output, inspect budget.timed out even after exit 0: empty timed out hits do not prove that no history exists. view C 3 limits surrounding lines, not bytes or tokens; a single JSONL record can be large. Check its output size before adding excerpts to a prompt. Hybrid remains the product default. Explicit lexical mode keeps this workflow out of semantic inference; no maintenance prevents index repair, catch up, and daemon auto spawn. If it returns maintenance required , report that blocker and stop this retrieval attempt. Do not turn a summary request into an index, repair, model install, wildcard aggregate, or repeated health/status workflow. Use readiness commands when diagnosing readiness; review their proposed actions before starting a separate mutating task. Broaden dates or terms deliberately after a completed query; choose semantic/hybrid only when conceptual retrieval is needed and its cost is acceptable. Preserve source/line citations in summaries. Essential Commands Why Use CASS Cross Agent Knowledge Transfer Your coding agents create scattered knowledge: Claude Code sessions in ~/.claude/projects Codex sessions in ~/.codex/sessions Cursor state in SQLite databases Aider history in markdown files CASS unifies all of this into a single searchable index. When you're stuck on a problem, search across ALL your past agent sessions to find relevant solutions. Use Cases Command Reference Indexing Search Session Analysis Status & Diagnostics Aggregation & Analytics Aggregate search results server side to get counts and distributions without transferring full result data: Aggregations reduce output volume, not necessarily scan work. They are not the first step for a quick history question; use the scoped retrieval recipe above. Aggregation Field Description agent Group by agent type (claude code, codex, cursor, etc.) workspace Group by workspace/project path date Group by date (YYYY MM DD) match type Group by match quality (exact, prefix, fuzzy) Top 10 buckets returned per field, with other count for remaining items. Remote Sources (Multi Machine Search) Search across sessions from multiple machines via SSH/rsync. Setup Wizard (Recommended) The wizard: 1. Discovers SSH hosts from ~/.ssh/config 2. Probes each for agent data and cass installation 3. Optionally installs cass on remotes 4. Indexes sessions on remotes 5. Configures sources.toml 6. Syncs data locally Manual Setup Configuration stored in ~/.config/cass/sources.toml (Linux) or ~/Library/Application Support/cass/sources.toml (macOS). Robot Mode Deep Dive Self Documenting API CASS teaches agents how to use itself: Forgiving Syntax (Agent Friendly) CASS auto corrects common mistakes: What you type What CASS understands cass serach "error" cass search "error" (typo corrected) cass robot limit=5 cass robot limit=5 (single dash fixed) cass Robot LIMIT 5 cass robot limit 5 (case normalized) cass find "auth" cass search "auth" (alias resolved) cass limt 5 cass limit 5 (Levenshtein <=2) Command Aliases: find , query , q , lookup , grep → search ls , list , info , summary → stats st , state → status reindex , idx , rebuild → index show , get , read → view docs , help robot , robotdocs → robot docs Output Formats Design principle: stdout = JSON only; diagnostics go to stderr. Token Budget Management LLMs have context limits. Control output size: Flag Effect fields minimal Only source path , line number , agent fields summary Adds title , score fields score,title,snippet Custom field selection max content length 500 Truncate long fields (UTF 8 safe) max tokens 2000 Soft budget (~4 chars/token) limit 5 Cap number of results Truncated fields include truncated: true indicator. Structured Error Handling Errors are JSON with actionable hints: Exit Codes Code Meaning Action 0 Success Parse stdout 1 Health check failed Inspect the reported condition; no automatic rebuild 2 Usage error Fix syntax (hint provided) 3 Index/DB missing Report missing assets; indexing is a separate mutating task 4 Network error Check connectivity 5 Data/maintenance failure Read error kind; preserve the archive and report the blocker 6 Incompatible version Update cass 7 Lock/busy Retry later 8 Partial result Report incomplete coverage; do not silently retry 9 Unknown error Check retryable flag Codes are command specific: consult cass robot docs exit codes and the JSON error kind. Search budget expiry can return exit 0 with budget.timed out=true ; session path output instead uses exit 10 for timeout. Search Modes Three search modes, selectable with mode flag: Mode Algorithm Best For lexical BM25 full text Exact term matching, bounded history recipes semantic Vector similarity Conceptual queries, "find similar" hybrid (default) Reciprocal Rank Fusion Lexical retrieval with semantic refinement when ready Hybrid combines lexical and semantic using RRF: Pipeline Mode (Chained Search) Chain searches by piping session paths: Use cases: Drill down : Broad search → narrow within results Cross reference : Find sessions with term A, then find term B within them Corpus building : Save session lists for repeated searches Query Language Basic Queries Query Matches error Messages containing "error" (case insensitive) python error Both "python" AND "error" "authentication failed" Exact phrase Boolean Operators Operator Example Meaning AND python AND error Both terms required (default) OR error OR warning Either term matches NOT error NOT test First term, excluding second error test Shorthand for NOT Wildcard Patterns Pattern Type Performance auth Prefix Fast (edge n grams) tion Suffix Slower (regex) config Substring Slowest (regex) Match Types Results include match type : Type Meaning Score Boost exact Verbatim match Highest prefix Via prefix expansion High suffix Via suffix pattern Medium substring Via substring pattern Lower fuzzy Auto fallback (sparse results) Lowest Auto Fuzzy Fallback When exact query returns <3 results, CASS automatically retries with wildcards: auth → auth Results flagged with wildcard fallback: true Flexible Time Input CASS accepts a wide variety of time/date formats: Format Examples Relative 7d , 24h , 30m , 1w Keywords now , today , yesterday ISO 8601 2024 11 25 , 2024 11 25T14:30:00Z US Dates 11/25/2024 , 11 25 2024 Unix Timestamp 1732579200 (seconds or milliseconds) Ranking Modes Cycle with F12 in TUI or use ranking flag: Mode Formula Best For Recent Heavy relevance 0.3 + recency 0.7 "What was I working on?" Balanced relevance 0.5 + recency 0.5 General search Relevance relevance 0.8 + recency 0.2 "Best explanation of X" Match Quality Penalizes fuzzy matches Precise technical searches Date Newest Pure chronological Recent activity Date Oldest Reverse chronological "When did I first..." Score Components Text Relevance (BM25) : Term frequency, inverse document frequency, length normalization Recency : Exponential decay (today ~1.0, last week ~0.7, last month ~0.3) Match Exactness : Exact phrase=1.0, Prefix=0.9, Suffix=0.8, Substring=0.6, Fuzzy=0.4 Blended Scoring Formula Mode α Value Effect Recent Heavy 1.0 Recency dominates Balanced 0.4 Moderate recency boost Relevance Heavy 0.1 BM25 dominates Match Quality 0.0 Pure text matching Supported Agents (23 Connectors) Agent Location Format Claude Code ~/.claude/projects JSONL Codex ~/.codex/sessions JSONL (Rollout) 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 SQLite (state.vscdb) ChatGPT ~/Library/Application Support/com.openai.chat JSON (v1 unencrypted) Aider ~/.aider.chat.history.md + per project Markdown Pi Agent ~/.pi/agent/sessions JSONL with thinking Factory (Droid) ~/.factory/sessions JSONL by workspace GitHub Copilot Chat VS Code global storage JSON / SQLite GitHub Copilot CLI ~/.copilot/session state JSONL OpenClaw ~/.openclaw JSONL ClawdBot ~/.clawdbot JSONL Vibe ~/.vibe/logs/session JSONL Crush ~/.crush/crush.db SQLite Hermes ~/.hermes JSONL Kimi Code ~/.kimi/sessions JSONL Qwen Code ~/.qwen/tmp JSON / JSONL OpenHands ~/.openhands/conversations JSON event stream Antigravity ~/.gemini/antigravity cli JSONL / SQLite Grok Build $GROK HOME/sessions (default ~/.grok/sessions ) ACP updates JSONL Note: ChatGPT v2/v3 are AES 256 GCM encrypted (keychain access required). Legacy v1 unencrypted conversations are indexed automatically. TUI Features (for Humans) Launch with cass (no flags): Keyboard Shortcuts Navigation: Up/Down : Move selection Left/Right : Switch panes Tab/Shift+Tab : Cycle focus Enter : Open in $EDITOR Space : Full screen detail view Home/End : Jump to first/last result PageUp/PageDown : Scroll by page Filtering: F3 : Agent filter F4 : Workspace filter F5/F6 : Time filters (from/to) Shift+F3 : Scope to current result's agent Shift+F4 : Clear workspace filter Shift+F5 : Cycle presets (24h/7d/30d/all) Ctrl+Del : Clear all filters Modes: F2 : Toggle theme (6 presets) F7 : Context window size (S/M/L/XL) F9 : Match mode (prefix/standard) F12 : Ranking mode Ctrl+B : Toggle border style Selection & Actions: m : Toggle selection Ctrl+A : Select all A : Bulk actions menu Ctrl+Enter : Add to queue Ctrl+O : Open all queued y : Copy path/content Ctrl+Y : Copy all selected / : Find in detail pane n/N : Next/prev match Views & Palette: Ctrl+P : Command pale