cass

# 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! ```bash # WRONG - blocks terminal cass # CORRECT - JSON output for agents cass search "query" --robot cass search "query" --json # alias ``` **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. ```bash # Specific terms, one workspace, recent history, small cited result set cass search "performance regression" --workspace /path/to/project --days 7 \ --mode lexical --no-maintenance --robot --robot-meta --fields minimal \ --limit 5 --max-tokens 2000 --timeout 2000 # Expand only a useful hit, using its exact source_path and line_number cass view /path/to/session.jsonl -n 42 -C 3 --json --timeout 2000 ``` `--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 ```bash # Find the current session for this workspace cass sessions --current --json # List recent sessions for a specific project cass sessions --workspace "$(pwd)" --json --limit 5 # Common agent flow: find current session, then export it cass export-html "$(cass sessions --current --json | jq -r '.sessions[0].path')" --json # Search with JSON output cass search "authentication error" --robot --limit 5 # Search with metadata (elapsed_ms, cache stats, freshness) cass search "error" --robot --robot-meta # Minimal payload (path, line, agent only) cass search "bug" --robot --fields minimal # View source at specific line cass view /path/to/session.jsonl -n 42 --json # Expand context around a line cass expand /path/to/session.jsonl -n 42 -C 5 --json # Capabilities discovery cass capabilities --json # Full API schema cass introspect --json # LLM-optimized documentation cass robot-docs guide cass robot-docs commands cass robot-docs schemas cass robot-docs examples cass robot-docs exit-codes ``` --- ## 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 ```bash # "I solved this before..." cass search "TypeError: Cannot read property" --robot --days 30 # Cross-agent learning (what has ANY agent said about X?) cass search "authentication" --robot --workspace /path/to/project # Agent-to-agent handoff cass search "database migration" --robot --fields summary # Daily review cass timeline --today --json ``` --- ## Command Reference ### Indexing ```bash # Full rebuild of DB and search index cass index --full # Incremental update (since last scan) cass index # Watch mode: auto-reindex on file changes cass index --watch # Force rebuild even if schema unchanged cass index --full --force-rebuild # Safe retries with idempotency key (24h TTL) cass index --full --idempotency-key "build-$(date +%Y%m%d)" # JSON output with stats cass index --full --json ``` ### Search ```bash # Basic search (JSON output required for agents!) cass search "query" --robot # With filters cass search "error" --robot --agent claude --days 7 cass search "bug" --robot --workspace /path/to/project cass search "panic" --robot --today # Time filters cass search "auth" --robot --since 2024-01-01 --until 2024-01-31 cass search "test" --robot --yesterday cass search "fix" --robot --week # Wildcards cass search "auth*" --robot # prefix: authentication, authorize cass search "*tion" --robot # suffix: authentication, exception cass search "*config*" --robot # substring: misconfigured # Token budget management (critical for LLMs!) cass search "error" --robot --fields minimal # path, line, agent only cass search "error" --robot --fields summary # adds title, score cass search "error" --robot --max-content-length 500 # truncate fields cass search "error" --robot --max-tokens 2000 # soft budget (~4 chars/token) cass search "error" --robot --limit 5 # cap results # Pagination (cursor-based) cass search "TODO" --robot --robot-meta --limit 20 # Use _meta.next_cursor from response: cass search "TODO" --robot --robot-meta --limit 20 --cursor "eyJ..." # Match highlighting cass search "authentication error" --robot --highlight # Query analysis/debugging cass search "auth*" --robot --explain # parsed query, cost estimates cass search "auth error" --robot --dry-run # validate without executing # Aggregations (server-side counts) cass search "error" --robot --aggregate agent,workspace,date # Request correlation cass search "bug" --robot --request-id "req-12345" # Source filtering (for multi-machine setups) cass search "auth" --robot --source laptop cass search "error" --robot --source remote # Traceability (for debugging agent pipelines) cass search "error" --robot --trace-file /tmp/cass-trace.json ``` ### Session Analysis ```bash # Export conversation to markdown/HTML/JSON cass export /path/to/session.jsonl --format markdown -o conversation.md cass export /path/to/session.jsonl --format html -o conversation.html cass export /path/to/session.jsonl --format json --include-tools # Expand context around a line (from search result) cass expand /path/to/session.jsonl -n 42 -C 5 --json # Shows 5 messages before and after line 42 # View source at line cass view /path/to/session.jsonl -n 42 --json # Activity timeline cass timeline --today --json --group-by hour cass timeline --days 7 --json --agent claude cass timeline --since 7d --json # Find related sessions for a file cass context /path/to/source.ts --json ``` ### Status & Diagnostics ```bash # Readiness diagnosis, when needed; not a prerequisite for every query cass health --json # Full status snapshot cass status --json cass state --json # alias # Statistics cass stats --json cass stats --by-source # for multi-machine # Full diagnostics cass diag --verbose ``` --- ## 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. ```bash # Count results by agent cass search "error" --robot --aggregate agent # → { "aggregations": { "agent": { "buckets": [{"key": "claude_code", "count": 45}, ...] } } } # Multi-field aggregation cass search "bug" --robot --aggregate agent,workspace,date # Combine with filters cass search "TODO" --agent claude --robot --aggregate workspace ``` | 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) ```bash cass sources setup ``` 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 ```bash cass sources setup --hosts css,csd,yto # Specific hosts only cass sources setup --dry-run # Preview without changes cass sources setup --resume # Resume interrupted setup ``` ### Manual Setup ```bash # Add a remote machine cass sources add user@laptop.local --preset macos-defaults cass sources add dev@workstation --path ~/.claude/projects --path ~/.codex/sessions # List sources cass sources list --json # Sync sessions cass sources sync cass sources sync --source laptop --verbose # Check connectivity cass sources doctor cass sources doctor --source laptop --json # Path mappings (rewrite remote paths to local) cass sources mappings list laptop cass sources mappings add laptop --from /home/user/projects --to /Users/me/projects cass sources mappings test laptop /home/user/projects/myapp/src/main.rs # Remove source cass sources remove laptop --purge -y ``` 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: ```bash # Quick capability check cass capabilities --json # Returns: features, connectors, limits # Full API schema cass introspect --json # Returns: all commands, arguments, response shapes # Topic-based docs (LLM-optimized) cass robot-docs commands # all commands and flags cass robot-docs schemas # response JSON schemas cass robot-docs examples # copy-paste invocations cass robot-docs exit-codes # error handling cass robot-docs guide # quick-start walkthrough cass robot-docs contracts # API versioning cass robot-docs sources # remote sources guide ``` ### 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 ```bash # Pretty-printed JSON (default) cass search "error" --robot # Streaming JSONL (header + one hit per line) cass search "error" --robot-format jsonl # Compact single-line JSON cass search "error" --robot-format compact # With performance metadata cass search "error" --robot --robot-meta ``` **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: ```json { "error": { "code": 3,