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 Pre Flight Check 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: 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 Run cass index full 2 Usage error Fix syntax (hint provided) 3 Index/DB missing Run cass index full 4 Network error Check connectivity 5 Data corruption Run cass index full force rebuild 6 Incompatible version Update cass 7 Lock/busy Retry later 8 Partial result Increase timeout 9 Unknown error Check retryable flag Search Modes Three search modes, selectable with mode flag: Mode Algorithm Best For lexical (default) BM25 full text Exact term matching, code searches semantic Vector similarity Conceptual queries, "find similar" hybrid Reciprocal Rank Fusion Balanced precision and recall 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 palette 1 9 : Load saved view Shift+1 9 : Save view to slot Source Filtering (multi machine): F11 : Cycle source filter (all/local/remote) Shift+F11 : Source selection menu Global: Ctrl+C : Quit F1 or ? : Toggle help Ctrl+Shift+R : Force re index Ctrl+Shift+Del : Reset all TUI state Detail Pane Tabs Tab Content Switch With Messages Full conversation with markdown [ / ] Snippets Keyword extracted summaries [ / ] Raw Unformatted JSON/text [ / ] Context Window Sizing Size Characters Use Case Small ~200 Quick scanning Medium ~400 Default balanced view Large ~800 Longer passages XLarge ~1600 Full context, code review Peek Mode ( Ctrl+Space ): Temporarily expand to XL without changing default. Theme Presets Cycle through 6 built in themes with F2 : Theme Description Best For Dark Tokyo Night inspired deep blues Low light environments Light High contrast light background Bright environments Catppuccin Warm pastels, reduced eye strain All day coding Dracula Purple accented dark theme Popular developer theme Nord Arctic inspired cool tones Calm, focused work High Contrast Maximum readability Accessibility needs All themes validated against WCAG contrast requirements (4.5:1 minimum for text). Role Aware Message Styling Role Visual Treatment User Blue tinted background, bold Assistant Green tinted background System Gray/muted background Tool Orange tinted background Saved Views Save filter configurations to 9 slots for instant recall. What Gets Saved: Active filters (agent, workspace, time range) Current ranking mode The search query Keyboard: Shift+1 through Shift+9 : Save current view 1 through 9 : Load view from slot Via Command Palette: Ctrl+P → "Save/Load view" Views persist in tui state.json across sessions. Density Modes Control lines per search result. Cycle with Shift+D : Mode Lines Best For Compa