🔎 coding-agent-search (cass)

Unified, high-performance TUI to index and search your local coding agent history. Aggregates sessions from Codex, Claude Code, Gemini CLI, Cline, OpenCode, Amp, Cursor, ChatGPT, Aider, Pi-Agent, Prime Agent, Oh My Pi, GitHub Copilot Chat, Copilot CLI, OpenClaw, Clawdbot, Vibe, Crush, Goose, Hermes, Kimi Code, Muse Code, Qwen Code, Factory (Droid), Antigravity, OpenHands, Grok Build, Grok Bot, Codebuff/Freebuff, Devin CLI, Shelley, and Kiro CLI into a single, searchable timeline.

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.sh?$(date +%s)" \
  | bash -s -- --easy-mode --verify

# Windows (PowerShell)
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.ps1"))) -EasyMode -Verify

Installs the latest release by default. Pass --version / -Version to pin a specific version.

Or via package managers:

# Homebrew (Apple Silicon macOS + Linux)
brew install dicklesworthstone/tap/cass

# Windows (Scoop)
scoop bucket add dicklesworthstone https://github.com/Dicklesworthstone/scoop-bucket
scoop install dicklesworthstone/cass

The Homebrew tap installs prebuilt release tarballs (not bottles) for Linux and Apple Silicon macOS. On Intel macOS, use the install script with --from-source.

🤖 Agent Quickstart (Robot Mode)

⚠️ Never run bare cass in an agent context — it launches the interactive TUI. Always use --robot or --json.

# 1) Check the installed interface once per version (recipe verified on 0.8.0).
cass --version
cass search --help

# Verify a newly installed executable without opening the configured archive.
cass selftest --json
# `health --binary-only` still reports (and therefore probes) archive readiness.

# 2) For a quick history question, start with scoped read-only lexical retrieval.
#    Hybrid remains the product default; lexical is explicit for this workflow.
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

# 3) Find the current or recent session for this workspace
cass sessions --current --json
cass sessions --workspace "$(pwd)" --json --limit 5

# 4) View + expand a hit (use source_path/line_number from search output)
cass view /path/to/session.jsonl -n 42 -C 3 --json --timeout 2000

# 5) Discover the full machine API
cass capabilities --json
cass robot-docs guide
cass robot-docs schemas

# 6) Exclude a noisy agent harness from future indexing
cass sources agents list --json
cass sources agents exclude openclaw
cass sources agents include openclaw

The retrieval flags above are available in 0.8.0. On older builds, check help; if --no-maintenance is absent, report the mismatch instead of dropping the read-only constraint. --timeout is in milliseconds, while --max-tokens limits approximate output size. Also set a caller-side deadline (for example, GNU timeout 10s); an externally interrupted command may leave incomplete JSON. Inspect budget.timed_out even after exit 0: timed-out empty hits are not proof that no history exists. A maintenance-required response ends the retrieval attempt; indexing or repair is a separate mutating task. Use triage/health/status for readiness diagnosis, not as repeated prerequisites to a short summary. Broaden scope deliberately, expand useful hits, and preserve source/line citations. view -C bounds context lines, not bytes; check excerpt size before including a long JSONL record in an agent prompt.

Output conventions

• stdout = data only
• stderr = diagnostics
• exit 0 = success

Search asset contract

• SQLite is the source of truth for indexed conversations and messages. All derived assets (lexical index, semantic vectors, analytics rollups, retention backups) can be rebuilt from SQLite; no derived asset is authoritative.
• Lexical search is the required fast path. Missing, stale, or incompatible lexical assets are treated as derived-state problems that cass should rebuild from SQLite instead of asking operators to perform routine manual repair.
• Hybrid is the default search intent. Robot metadata (--robot --robot-meta) reports the requested mode, realized mode, semantic refinement status, and any lexical fallback reason when semantic assets are not ready.
• Semantic assets are opportunistic background enrichment. Lexical-only results are expected during first indexing, semantic catch-up, disabled semantic policy, or unavailable local model/vector files.
• Semantic model acquisition is opt-in: cass models install downloads the default all-minilm-l6-v2 (alias minilm, ~90 MB) only on explicit request; --model multilingual-minilm selects the larger multilingual MiniLM L12 model (~480 MB) for CJK/mixed-language archives. Cass never auto-downloads or auto-selects the multilingual space. Air-gapped installs use --from-file . While the selected model is absent, hybrid search uses lexical-only and reports fallback_mode="lexical" in health/status.
• cass triage --json combines readiness, next_command, recommended_commands[], docs/schema pointers, starter workflows, and accepted recoveries for diagnosis. Review recommended mutations before executing them. cass health --json and cass status --json remain the narrower truth surfaces for readiness, active rebuilds, and recovery.

Lexical publish durability (atomic-swap)

• Every lexical publish is an atomic renameat2(RENAME_EXCHANGE) on Linux, or a parked-rename + restore-on-failure dance elsewhere. Readers never see a half-torn index — they see either the old or the new generation, never a mix. See src/indexer/mod.rs::publish_staged_lexical_index.
• The prior-live generation is retained under /index/.lexical-publish-backups// for a bounded retention window. Default cap is 1 (keep just the most-recent prior generation for one-step rollback); override via the CASS_LEXICAL_PUBLISH_BACKUP_RETENTION env var (0 disables retention entirely, higher N keeps deeper history). Pruning runs after every successful publish and emits structured tracing::info! events with freed_bytes + retention_limit for observability.
• Crash recovery is automatic: a crash between the atomic swap and the retain-rename is handled by recover_or_finalize_interrupted_lexical_publish_backup at the start of the next lexical publish or rebuild (not at process startup), which moves any orphaned canonical sidecar (..publish-in-progress.bak) into .lexical-publish-backups/ before the next publish lands.

Quarantine, GC, and the doctor/diag surface

• Corrupt or failed-validation assets are quarantined rather than auto-deleted. cass diag --json --quarantine enumerates every quarantined derived artifact (failed seed bundles, retained publish backups, quarantined lexical generations; conversations excluded at ingest are listed by cass quarantine list --json) with size_bytes, age_seconds, safe_to_gc, and a human-readable gc_reason. The safe_to_gc flag is advisory — it reflects retention policy + cleanup dry-run eligibility and is not wired to any automatic deletion path.
• cass doctor --json surfaces the same quarantine summary plus checks[] status for every diagnostic the tool runs. Without --fix, doctor is read-only (auto_fix_applied=false, auto_fix_actions=[], issues_fixed=0); with --fix it applies only the repairs whose dry-run plans are proven safe (currently: Track A analytics rebuild, Track B rollup rebuild via rebuild_token_daily_stats when the token_usage ledger is intact).
• Lexical generation cleanup uses a dispositions + inspection-required-first policy. Operators running cass doctor --fix never have a generation reclaimed silently — every quarantine stays on disk until an explicit derived-asset rebuild (cass models backfill or an index refresh recommended by cass health --json) supersedes it.
• A derived (SQLite fallback) FTS repair that fails identically on 5 consecutive cass index runs escalates from a warning to a non-zero exit (#434): the counter persists in /index/.fts-repair-failure-streak.json, watch daemons log the escalation instead of exiting, and any run whose repair succeeds — or fails differently — resets it. Canonical rows and the Tantivy index are unaffected; run cass doctor --rebuild-canonical-fts --yes --json for the explicit repair.

Schema stability guarantees

• JSON contract surfaces are pinned by golden-file regression tests under tests/golden/robot/: capabilities, selftest, health, status, diag, models status/verify/check-update, introspect, doctor, api-version, stats, search, export-html, onboarding, the quarantine and dedup commands and analytics incidents, plus sessions and pack on their missing-database and error paths only. swarm status scenarios are pinned under tests/golden/swarm_status/. triage, swarm work-packet and swarm lint have no golden files; their shape is covered only by assertion tests. A change to any field name, type, or nullability fails the golden test suite and requires a deliberate regeneration pass (UPDATE_GOLDENS=1 rch exec -- env CARGO_TARGET_DIR=/data/tmp/cass-golden-target cargo test --test golden_robot_json --test golden_robot_docs).
• cass introspect --json's response_schemas block enumerates every schema in a stable alphabetical order (BTreeMap-backed — see bead coding_agent_session_search-8sl73).
• Error envelopes ({error: {code, kind, message, hint, retryable}}) have a fixed shape. kind values are kebab-case; branch on err.kind, not on the numeric code, for codes ≥ 10 (see the Error Handling section below).

📬 Agent Mail Fallback (When MCP Tools Are Not Exposed)

If your runtime does not expose built-in mcp-agent-mail tools (for example, list_mcp_resources is empty), you can still coordinate via direct MCP HTTP calls.

1) Start the local Agent Mail server

~/.local/pipx/venvs/mcp-agent-mail/bin/python -m mcp_agent_mail.cli serve-http --host 127.0.0.1 --port 8765

2) Use the Streamable HTTP MCP endpoint (/mcp)

curl -sS -X POST http://127.0.0.1:8765/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"health","method":"tools/call","params":{"name":"health_check","arguments":{}}}'

3) Minimal coordination flow (project -> agent -> message -> inbox -> ack)

# Ensure project
curl -sS -X POST http://127.0.0.1:8765/mcp -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"ensure","method":"tools/call","params":{"name":"ensure_project","arguments":{"human_key":"/data/projects/coding_agent_session_search"}}}'

# Register agent
curl -sS -X POST http://127.0.0.1:8765/mcp -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"register","method":"tools/call","params":{"name":"register_agent","arguments":{"project_key":"/data/projects/coding_agent_session_search","program":"codex","model":"gpt-5","name":"YourAgentName"}}}'

# Send message
curl -sS -X POST http://127.0.0.1:8765/mcp -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"send","method":"tools/call","params":{"name":"send_message","arguments":{"project_key":"/data/projects/coding_agent_session_search","sender_name":"YourAgentName","to":["PeerAgent"],"subject":"[coord] hello","thread_id":"coord-2026-02-13","ack_required":true,"body_md":"Online and starting work."}}}'

# Fetch inbox
curl -sS -X POST http://127.0.0.1:8765/mcp -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"inbox","method":"tools/call","params":{"name":"fetch_inbox","arguments":{"project_key":"/data/projects/coding_agent_session_search","agent_name":"YourAgentName","limit":50,"include_bodies":true}}}'

# Acknowledge message id 42
curl -sS -X POST http://127.0.0.1:8765/mcp -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"ack","method":"tools/call","params":{"name":"call_extended_tool","arguments":{"tool_name":"acknowledge_message","arguments":{"project_key":"/data/projects/coding_agent_session_search","agent_name":"YourAgentName","message_id":42}}}}'

Important caveat

mcp_agent_mail defaults to sqlite+aiosqlite:///./storage.sqlite3. That means the server working directory determines which mailbox database you are using. To avoid "project not found" confusion, start the server from the same directory your team expects for mailbox state.

📸 Screenshots

Search Results Across All Your Agents

Three-pane layout with semantic styling: filter bar with pills, results list with color-coded agents and score tiers, and syntax-highlighted detail preview with tab navigation

Rich Conversation Detail View

Full conversation rendering with markdown formatting, code blocks, headers, and structured content

Quick Start & Keyboard Reference

Built-in help screen (press F1 or ?) with all shortcuts, filters, modes, and navigation tips

💡 Why This Exists

The Problem

AI coding agents are transforming how we write software. Claude Code, Codex, Cursor, Copilot, Aider, Pi-Agent; each creates a trail of conversations, debugging sessions, and problem-solving attempts. But this wealth of knowledge is scattered and unsearchable:

• Fragmented storage: Each agent stores data differently—JSONL files, SQLite databases, markdown logs, proprietary JSON formats
• No cross-agent visibility: Solutions discovered in Cursor are invisible when you're using Claude Code
• Lost context: That brilliant debugging session from two weeks ago? Good luck finding it by scrolling through files
• No semantic search by default: File-based grep doesn't understand natural language queries; cass can add optional local ML search when model files are installed

The Solution

cass treats your coding agent history as a unified knowledge base. It:

1. Normalizes disparate formats into a common schema
2. Indexes everything with a purpose-built full-text search engine
3. Surfaces relevant past conversations in milliseconds
4. Respects your privacy—everything stays local, nothing phones home

Who Benefits

• Individual developers: Find that solution you know you've seen before
• Teams: Share institutional knowledge across different tool preferences
• AI agents themselves: Let your current agent learn from all your past agents (via robot mode)
• Power users: Build workflows that leverage your complete coding history

✨ Key Features

⚡ Instant Search (Sub-60ms Latency)

• "Search-as-you-type": Results update instantly with every keystroke.
• Edge N-Gram Indexing: We frontload the work by pre-computing prefix matches (e.g., "cal" -> "calculate") during indexing: 2–20 character prefixes of every word in titles and in the first 4 KiB of each message, trading disk space for fast lookup at query time.
• Smart Tokenization: Handles snake_case ("my_var" matches "my" and "var"), hyphenated terms, and code symbols (c++, foo.bar) correctly.
• Zero-Stall Updates: The background indexer commits changes atomically; reader.reload() ensures new messages appear in the search bar immediately without restarting.
• One-shot CLI overhead: the sub-60ms figure is the engine query. A one-shot cass search --robot currently spends roughly a second in archive open and integrity preflight on a ~10 GB archive; --robot-meta reports that separately as _meta.timing.other_ms, while search_ms stays in the tens of milliseconds.

🧠 Optional Semantic Search (Local Inference, No Network at Query Time)

• Local inference: Uses frankensearch's pure-Rust native MiniLM implementation with local safetensors weights. Once MiniLM is installed, no network traffic is required to answer queries.

• Warm-daemon reuse: Semantic and hybrid CLI searches automatically use an already-running local embedding daemon (including a socket selected with CASS_DAEMON_SOCKET) and only initialize the installed in-process model if daemon inference fails. Pass --daemon to permit auto-spawning a missing daemon in human-mode searches (robot/JSON searches never spawn one, even with --daemon, because their bounded budget cannot wait for a daemon to start; start cass daemon yourself first; _meta.effective.daemon shows the request and what applied), or --no-daemon to force direct inference. --fast-only stays in the deterministic hash-vector space. Each data directory gets a distinct default socket and owner-private pinned key; fresh handshake, health, embedding, batch, and rerank challenges authenticate the exact response and immutable Frankensearch embedding identity before any daemon output is used. --two-tier progressive refinement (fast results refined in place by the quality tier) is experimental and currently inactive: the one-shot CLI collapses it to a single-tier quality search and the TUI's progressive lanes are disabled at HEAD, so hybrid search today is lexical plus one MiniLM refinement pass when the model is installed.

• Opt-in acquisition: cass models install downloads all-minilm-l6-v2 from Hugging Face on explicit request and verifies SHA256 checksums. cass models install --model multilingual-minilm explicitly selects paraphrase-multilingual-MiniLM-L12-v2 for CJK and mixed-language retrieval. Nothing is fetched until an install command runs, and merely installing the multilingual model never changes the active space.

• Air-gapped install: cass models install --model --from-file accepts a pre-downloaded model directory so you can bring the assets in yourself.

• Switching spaces: both models output 384 values, but their identities and vectors are incompatible. Set CASS_SEMANTIC_EMBEDDER=multilingual-minilm, then run cass models backfill --tier quality --embedder multilingual-minilm; cass keeps lexical fail-open active until the complete new generation is atomically published.

• Required files (all must be present after install; cass models verify --model checks the selected model):

  • model.safetensors
  • tokenizer.json
  • config.json
  • special_tokens_map.json
  • tokenizer_config.json

• Vector index: Stored as vector_index/index-.fsvi in the data directory.

• Lexical fail-open: While the model is absent, cass returns lexical-only results and reports fallback_mode="lexical" in health/status; search never blocks on semantic assets.

Explicit Hash Vector Tier

The deterministic hash embedder is available only when explicitly selected, such as with --fast-only, --embedder hash, or CASS_SEMANTIC_EMBEDDER=hash. It is a separate lexical-feature vector space, not a silent substitute for missing MiniLM vectors:

Algorithm:

1. Tokenize: Lowercase, split on non-alphanumeric, filter tokens <2 characters
2. Hash: Apply FNV-1a to each token
3. Project: Use hash to determine dimension index and sign (+1 or -1) in a 384-dimensional vector
4. Normalize: L2 normalize to unit length for cosine similarity

When to Use:

• Quick setup without downloading model files
• Environments where ML inference overhead is unwanted
• Fast-tier testing or an explicitly chosen degraded mode

Override: Set CASS_SEMANTIC_EMBEDDER=hash to force hash mode even when ML model is available.

FSVI Vector Index Format

cass uses the frankensearch FSVI vector index format (.fsvi) for storing semantic embeddings.

Features:

• Memory-mappable: large indexes open without copying into RAM
• Quantization: supports f32 and f16 storage for smaller on-disk size
• Fast search: exact brute-force vector search by default; HNSW approximate search runs only when --approximate is passed and the HNSW sidecar file exists. hnsw_ready in status --json means only that the sidecar file is present, not that ANN is in use

Index Location: ~/.local/share/coding-agent-search/vector_index/index-.fsvi

Search Modes

cass supports three search modes, selectable via --mode flag or Alt+S in the TUI:

Lexical Search: Uses Quill's BM25 implementation with prefix matching. Best when you know the exact terms you're looking for. The lexical index is derived from SQLite; if it is missing, stale, or incompatible, cass reports the state and rebuilds through the normal indexing path from the canonical database.

Semantic Search: Computes vector similarity between query and indexed MiniLM embeddings. Finds conceptually related content even without exact term overlap. Explicit semantic mode requires the MiniLM model and a compatible MiniLM vector index; it never substitutes same-dimensional hash vectors.

Hybrid Search: The default. It combines lexical and semantic results using Reciprocal Rank Fusion (RRF) when semantic assets are ready, and it fails open to lexical when semantic enrichment is still catching up or disabled:

RRF_score = Σ 1 / (K + rank_i)

Where K=60 (tuning constant) and rank_i is the position in each result list. This balances the precision of lexical search with the recall of semantic search. Semantic refinement is a single pass over the installed MiniLM index; progressive two-tier refinement (--two-tier) is experimental and currently inactive.

# CLI examples
cass search "authentication" --mode lexical --robot
cass search "how to handle user login" --mode semantic --robot
cass search "auth error handling" --mode hybrid --robot

🎯 Advanced Search Features

• Wildcard Patterns: Full glob-style pattern support:
  • foo* - Prefix match (finds "foobar", "foo123")
  • *foo - Suffix match (finds "barfoo", "configfoo")
  • *foo* - Substring match (finds "afoob", "configuration")
• Auto-Fuzzy Fallback: On small indexes (up to 10,000 documents by default), an exact search with sparse results is retried with *term* wildcards to broaden matches. A visual indicator shows when the fallback is active.
• Query History Deduplication: Recent searches deduplicated to show unique queries; navigate with Up/Down arrows.
• Match Quality Ranking: New ranking mode (cycle with F12) that prioritizes exact matches over wildcard/fuzzy results.
• Match Highlighting: Snippets mark the terms the engine matched with **bold**, in human-readable and robot/JSON output alike; --highlight also marks the query terms' other occurrences, never marking a term twice.

🖥️ Rich Terminal UI (TUI)

Powered by FrankenTUI (ftui) — a high-performance Elm-architecture TUI framework with adaptive frame budgets, Bayesian diff selection, and spring-based animations.

• Three-Pane Layout: Filter bar (top), scrollable results (left), and syntax-highlighted details (right).
• Multi-Line Result Display: Each result shows location and up to 3 lines of context; alternating stripes improve scanability.
• Live Status: Footer shows real-time indexing progress—agent discovery count during scanning, then item progress as a progress bar labelled Indexing 150/2000 (7%)—plus active filters.
• Multi-Open Queue: Queue multiple results with Ctrl+Enter, then open all in your editor with Ctrl+O. Confirmation prompt for large batches (≥12 items).
• Find-in-Detail: Press / to search within the detail pane; matches highlighted with n/N navigation.
• Mouse Support: Click to select results, scroll panes, or clear filters.
• Theming: Adaptive Dark/Light modes with role-colored messages (User/Assistant/System). Presets include dark, light, high-contrast, and accessible variants.
• Ranking Modes: Cycle through recent/balanced/relevance/quality with F12; quality mode penalizes fuzzy matches.
• Analytics Dashboard: 7 views (Dashboard, Explorer, Heatmap, Breakdowns, Tools, Plans, Coverage) with interactive charts, KPI tiles, and drill-down filtering. Open with Alt+A; Esc returns to search.
• Inline Mode: Run cass tui --inline to keep terminal scrollback intact. The UI anchors to a region of the terminal while logs scroll normally. Configure with --ui-height and --anchor top|bottom.
• Macro Recording: Capture input sessions with cass tui --record-macro session.macro for reproducible bug reports and workflow automation. Events are saved as human-readable JSONL with full timing data.
• Asciicast Recording: Capture reproducible TUI demos and bug repro artifacts with cass tui --asciicast demo.cast.
  • Security default: recording captures terminal output only (input keystrokes are not serialized by default).

📄 HTML Session Export

Export conversations as styled, portable HTML files with optional encryption:

• Mostly Self-Contained: All layout CSS and the export payload are inlined directly; the file opens without a local web server and references no Tailwind CDN (Tailwind is not used at runtime). Only the Prism.js syntax-highlighting assets are loaded from cdn.jsdelivr.net, pinned with SRI hashes.
• Progressive Enhancement / Graceful Degradation: Prism.js resources fall back via onerror="...no-prism" — code blocks remain readable offline in plain monospace, and the page layout never depends on a network resource.
• Password Protection: AES-256-GCM encryption with PBKDF2 key derivation (600,000 iterations)—opens directly in any browser
• Rich Styling: Dark/light themes, syntax-highlighted code blocks, collapsible tool calls
• Print-Friendly: Optimized print styles with page breaks and footers
• Searchable: Built-in search functionality within the exported document

TUI Usage: Press Ctrl+E in the detail view to open the export modal, or Ctrl+Shift+E to export Markdown immediately with defaults. On the detail pane's Export tab, e/h open the HTML export modal and m runs the Markdown export.

CLI Usage:

# Basic export
cass export-html /path/to/session.jsonl

# With encryption
printf '%s\n' "secret" | cass export-html /path/to/session.jsonl --encrypt --password-stdin

# Custom output location
cass export-html session.jsonl --output-dir ~/exports --filename "my-session"

# Open in browser after export
cass export-html session.jsonl --open

# Robot mode (JSON output)
cass export-html session.jsonl --json

🔗 Universal Connectors

Ingests history from 32 local agent connectors, normalizing them into a unified Conversation -> Message -> Snippet model. cass capabilities --json | jq .connectors is the canonical machine-readable inventory (kept in lockstep with the runtime registry):

• Codex: ~/.codex/sessions (Rollout JSONL)
• Cline: VS Code global storage (Task directories)
• Gemini CLI: ~/.gemini/tmp (Chat JSON)
• Claude Code: ~/.claude/projects (Session JSONL), plus macOS Desktop metadata sidecars under ~/Library/Application Support/Claude/claude-code-sessions and ~/Library/Application Support/Claude/local-agent-mode-sessions
• Clawdbot: ~/.clawdbot/sessions (Session JSONL)
• Vibe (Mistral): ~/.vibe/logs/session/*/messages.jsonl (Session JSONL)
• OpenCode: .opencode directories (SQLite)
• Amp: ~/.local/share/amp & VS Code storage
• Cursor: ~/Library/Application Support/Cursor/User/ global + workspace storage (SQLite state.vscdb)
• ChatGPT: ~/Library/Application Support/com.openai.chat (v1 unencrypted JSON; v2/v3 encrypted—see Environment)
• Aider: ~/.aider.chat.history.md and per-project .aider.chat.history.md files (Markdown)
• Pi-Agent: ~/.pi/agent/sessions (Session JSONL with thinking content)
• Prime Agent (prime_agent): ~/.prime/agent/sessions/.jsonl (versions 1–3). Indexes the active branch with omission counts for abandoned siblings; preserves thinking, tool results and context summaries. Overrides, in precedence order: PRIME_AGENT_SESSION_DIR, legacy PRIME_AGENT_CODING_AGENT_SESSION_DIR, then PRIME_AGENT_CODING_AGENT_DIR (with /sessions appended). Prime retains its own agent identity.
• Oh My Pi (omp): OMP v18's default ~/.omp/agent/sessions, named profiles under ~/.omp/profiles//agent/sessions, XDG stores under $XDG_DATA_HOME/omp, and explicit OMP-only archive roots via CASS_OMP_DATA_ROOT (pi-family JSONL, including per-session sub-agent transcripts)
• GitHub Copilot Chat: VS Code global storage under github.copilot-chat (JSON)
• Copilot CLI: ~/.copilot/session-state, legacy ~/.copilot/history-session-state, and gh copilot config paths (JSONL/JSON)
• OpenClaw: ~/.openclaw/agents/*/sessions (Session JSONL)
• Goose: ~/.local/share/goose/sessions/sessions.db (SQLite, v1.20+), plus the earlier per-session *.jsonl layout under ~/.goose/sessions
• Crush: ~/.crush/crush.db and per-project .crush/crush.db (SQLite)
• Hermes: ~/.hermes/state.db and project-local .hermes/state.db (SQLite)
• Devin CLI: ~/.local/share/devin/cli/sessions.db (SQLite; override with CASS_DEVIN_DATA_ROOT). Indexes visible local sessions along their active parent chain, preserving tool messages and excluding abandoned branches and inline image payloads. Cloud-only sessions are outside this connector's scope.
• Shelley: reads the local SQLite conversation database directly. Set CASS_SHELLEY_DB=/absolute/path/to/shelley.db, or add that file to the paths of a type = "local" source in sources.toml. Any filename is accepted after schema validation. Defaults include ~/.config/shelley/shelley.db and shelley.db in the current directory. Live indexing watches the database and its WAL/SHM sidecars; metadata changes refresh existing sessions. CASS_SKIP_SUBAGENTS=1 excludes conversations with a Shelley parent ID. The database can also contain credentials and application settings, so raw mirroring and remote database ingestion are disabled; keep the database on its original machine.
• Grok Bot: indexes the desktop application's local rolling chat replica. Set CASS_GROK_BOT_DATA_ROOT to its persistence directory. Native message IDs preserve already indexed history as older messages leave the application's window; repeat scans do not duplicate retained messages. CASS reads only chat content. Raw mirroring and automatic fleet copying are disabled because the replica also holds secret and approval fields. This connector is separate from the Grok CLI connector and does not fetch cloud history.
• Kimi Code: $KIMI_CODE_HOME/sessions/*/*/agents/*/wire.jsonl (default ~/.kimi-code; sub-agents index as :), plus the legacy ~/.kimi/sessions/*/*/wire.jsonl layout (Session JSONL)
• Muse Code: ~/.local/share/muse/sessions/////session.jsonl, including nested subagent/*/session.jsonl transcripts (override with CASS_MUSE_DATA_ROOT)
• Qwen Code: ~/.qwen/tmp/*/chats/session-*.json (Chat JSON)
• Factory (Droid): ~/.factory/sessions (JSONL files organized by workspace slug)
• Antigravity (IDE + agy CLI): both stores are probed by default — the IDE's ~/.gemini/antigravity/ and the CLI's ~/.gemini/antigravity-cli/ — each holding brain//.system_generated/logs/transcript.jsonl (clean JSONL transcript) with the durable per-conversation conversations/.db (SQLite) mirrored alongside. IDE conversations are keyed ide/ so the two stores never collide; CASS_ANTIGRAVITY_DATA_ROOT replaces both with one explicit base. Resume with cass resume --agent agy (agy --conversation ).
• OpenHands (OpenDevin): ~/.openhands/conversations// — base_state.json metadata plus an events/event-NNNNN-.json event stream (JSON)
• Grok Build (xAI grok): ~/.grok/sessions/// — updates.jsonl (authoritative ACP session-update stream) with summary.json metadata and chat_history.jsonl fallback (override the base dir with GROK_HOME). Resume with grok --resume .
• Codebuff / Freebuff (codebuff): ~/.config/manicode/projects//chats//chat-messages.json with its run-state.json (override with CASS_CODEBUFF_DATA_ROOT). Both products write the same Manicode store and no chat records which binary wrote it, so their sessions share one lineage identity, codebuff (filter with --agent codebuff). Messages are reconciled by their native IDs, so an edited message updates in place instead of duplicating.
• Kiro CLI (kiro): ~/.kiro/sessions/cli/.jsonl (append-only event log: prompts, assistant messages, tool results) with the matching .json snapshot read for session ID, working directory, title, timestamps and model.

Claude Code Desktop sidecars preserve title, workspace, model, and session IDs, but not necessarily the full conversation body. If Claude Code has culled an old CLI JSONL body, cass can still index searchable sidecar metadata while reporting that the conversation body is unavailable.

Connector Details

Pi-Agent parses JSONL session files with rich event structure:

• Location: ~/.pi/agent/sessions/ (override the agent home with PI_CODING_AGENT_DIR, or the sessions directory directly with PI_SESSIONS_DIR)
• Format: Typed events—session_start, message, model_change, thinking_level_change
• Features: Extracts extended thinking content, flattens tool calls with arguments, tracks model changes
• Detection: Scans for *_*.jsonl pattern in sessions directory

Oh My Pi (omp) uses the same pi-family wire format but remains a separate agent identity throughout search, analytics, resume, TUI, and HTML export:

• Default and profiles: ~/.omp/agent/sessions/ and ~/.omp/profiles//agent/sessions/; OMP_PROFILE selects a profile and takes precedence over legacy PI_PROFILE
• XDG: $XDG_DATA_HOME/omp/sessions/ and $XDG_DATA_HOME/omp/profiles//sessions/ when the OMP XDG root exists
• Overrides and ownership: PI_CODING_AGENT_SESSION_DIR names the exact OMP sessions directory. CASS_OMP_DATA_ROOT declares an OMP-only archive/store root and is the right choice for copied, mounted, or custom OMP data. PI_CODING_AGENT_DIR is shared by both pi-family programs, so CASS conservatively keeps otherwise-ambiguous paths under that root owned by Pi-Agent; use one of the OMP-specific variables when OMP identity matters. PI_CONFIG_DIR changes the home-relative .omp config directory name.
• Resume: results in the current live home/config store use omp [--profile ] --resume ; copied profiles, XDG archives, remote mirrors, and explicit roots also carry --session-dir so a canonical-looking archive cannot reopen a different live store
• Upgrade behavior: archives created by older cass versions are reclassified from pi_agent to omp using the same conservative canonical/XDG/remote-mirror ownership policy as live discovery, then the derived lexical index and analytics are rebuilt so a transcript cannot remain attributed to both agents. The conventional ~/.local/share/omp shape is durable path evidence; an arbitrary historical custom $XDG_DATA_HOME/omp path is reclassified only while that root is currently configured and resolvable. Without provider-qualified evidence, ambiguous historical paths fail closed as Pi-Agent rather than letting a generic .../omp/sessions directory steal ownership.

OpenCode reads SQLite databases from workspace directories:

• Location: .opencode/ directories (scans recursively from home)
• Format: SQLite database with sessions table
• Detection: Finds directories named .opencode containing database files

🌐 Remote Sources (Multi-Machine Search)

Search across agent sessions from multiple machines—your laptop, desktop, and remote servers—all from a single unified index. cass uses SSH/rsync to efficiently sync session data, tracking provenance so you know where each conversation originated.

Interactive Setup Wizard (Recommended)

The easiest way to configure multi-machine search is the interactive setup wizard:

cass sources setup

What the wizard does:

1. Discovers SSH hosts from your ~/.ssh/config
2. Probes each host to check for:
   • Existing cass installation (and version)
   • Agent session data (Claude, Codex, Cursor, Gemini, etc.)
   • System resources (disk space, memory)
3. Lets you select which hosts to configure
4. Installs cass on remotes that don't have it (optional)
5. Indexes existing sessions on remotes (optional)
6. Configures sources.toml with correct paths and mappings
7. Syncs the configured remotes by running cass sources sync right after configuration (skipped with --skip-sync or --dry-run; --json setup defers it and reports the command to run)

Wizard options:

Examples:

# Full interactive wizard
cass sources setup

# Configure specific hosts only
cass sources setup --hosts laptop,workstation,build-server

# Preview without making changes
cass sources setup --dry-run

# Resume interrupted setup
cass sources setup --resume

# Non-interactive for CI/CD
cass sources setup --non-interactive --hosts myserver --skip-install

Resumable state: If setup is interrupted (Ctrl+C, connection lost), state is saved to the cache directory (~/.cache/cass/setup_state.json on Linux). Resume with --resume.

Testing your real fleet

Tailscale discovery is optional: cass sources discover --tailscale --json adds online tailnet peers to SSH-config discovery, and cass sources setup --tailscale offers them in setup. It reads local tailscale status --json with a five-second deadline; a missing CLI, stopped daemon, or login failure produces a warning and leaves SSH-config discovery available. Explicit setup --hosts skips discovery. Connections use ordinary SSH over assigned Tailscale IPv4 addresses, so MagicDNS is not required. Matching SSH aliases retain their user/key configuration; otherwise SSH uses its normal defaults. IPv6-only peers are currently omitted. Tailscale ACLs, SSH authorization and host-key checks still apply; discovery does not log in, install Tailscale, or change either SSH or tailnet configuration.

The local fixture and Docker tests do not prove that your machines can sync and search each other's sessions. The opt-in live harness uses actual SSH connections and cass sources discover, sources add, sources sync, and search. It creates isolated synthetic Codex sessions on each machine, checks source provenance and filters, repeats a sync to detect duplicates, and appends messages. It checks both lexical and default hybrid search, requires one JSON response per sync, holds the real indexing lock to test busy refusal, and recovers transferred sessions through sources reingest. A refused SSH connection must leave the other sources searchable.

Keep the inventory and SSH configuration outside this repository. For example, create a mode-0600 JSON file containing:

{
  "ssh_config": "/private/path/to/ssh_config",
  "hosts": [{"ssh": "workstation"}, {"ssh": "laptop"}]
}

Then run with an explicit binary:

python3 scripts/e2e/live_fleet_search.py \
  --inventory /private/path/to/fleet.json \
  --cass-bin /path/to/cass

Python 3 and authenticated SSH access are required on the remote machines. The Unix runner needs Python 3.9+, rsync, and a CASS binary supporting the tested commands. Each inventory alias must appear in the supplied SSH configuration; included configuration files are supported. Host-key verification stays enabled. To exercise actual tailnet discovery and transport, add --tailscale to the harness command and use tailnet IPv4 addresses as the private inventory targets. Keep any required SSH users, keys and trusted host-key aliases in the private SSH configuration. For a discovery test independent of explicit aliases, use SSH Match originalhost entries rather than literal Host entries for those addresses. The harness retains fresh test directories and raw receipts privately outside git; it never changes existing session archives or deletes test data. Console results use ordinal labels. An unreachable machine keeps the overall result failed, even if the other machines pass. Do not attach raw receipts or inventories to public issues: they contain machine identities.

Remote Installation Methods

When the wizard installs cass on remote machines, it tries every viable method in this priority order, falling through to the next when one fails; setup fails only when all of them do, and the error lists each attempt:

crates.io publishing resumed at 0.7.0 (GH#416): the long-stale registry gap (0.6.13, published before the Quill/OMP era) is closed — the entire dependency chain now resolves from crates.io (frankensearch 0.4.0, the frankentorch-* family, frankenhnsw), so cargo install coding-agent-search builds the current line again. The installer and GitHub Release binaries remain the fastest paths.

Resource Requirements:

• Minimum 1GB disk space for installation
• Recommended 2GB RAM for compilation
• Linux pre-built binaries require glibc 2.38+ on conventional FHS-style distributions; older glibc, musl-only, and NixOS hosts fall back to source installation when possible.
• SSH access with key-based authentication

What Gets Installed:

• The cass binary (location depends on method: ~/.cargo/bin/cass for cargo-based, ~/.local/bin/cass for pre-built binary)
• No daemon, no background services—just the binary

Installation Progress: The wizard shows real-time progress for each stage:

Installing cass on laptop...
  [1/4] Checking environment...     ✓
  [2/4] Downloading binary...       ████████░░ 80%
  [3/4] Verifying checksum...       ✓
  [4/4] Setting up PATH...          ✓

Use --skip-install if you prefer to install manually on remotes.

Host Discovery & Probing

The setup wizard automatically discovers SSH hosts from your configuration:

Discovery Sources:

• ~/.ssh/config (parses Host entries)
• Hosts with wildcards (*, ?) are automatically excluded

Probe Results (for each discovered host):

Each setup run probes every selected host afresh; probe results are not cached between runs.

Manual Setup

For manual configuration without the wizard:

# Add a remote machine using platform presets
cass sources add [email protected] --preset macos-defaults

# Or specify paths explicitly
cass sources add dev@workstation --path ~/.claude/projects --path ~/.codex/sessions

# Sync sessions from all configured sources
cass sources sync

# Check source health and connectivity
cass sources doctor

Remote Archive Safety

Remote source diagnostics are intentionally local-only. cass triage --json, cass doctor --json, cass health --json, and cass status --json report the remote_source_sync summary from cass-owned evidence: sources.toml, sync_status.json, the local remotes//mirror/ copy, and archive DB provenance rows. They do not open SSH sessions, mutate remote machines, or rewrite provider session logs while classifying source gaps.

cass sources doctor is the explicit networked exception: it performs bounded, read-only probes of configured source hosts. Its per-source human summary keeps the same native reachability, binary-health, and mirror/sync state codes and safe command as the JSON report. It intentionally does not claim local search readiness, because a remote host probe cannot establish the controller's local SQLite, lexical, or semantic asset state.

This matters because agent harnesses can prune their own logs. If a laptop is retired, a remote path disappears, or a provider truncates older sessions, the cass archive DB and cass-owned local mirror may be the only remaining evidence for those conversations. Treat gap names such as remote_source_unavailable, remote_source_pruned, local_archive_ahead_of_remote, and remote_copy_ahead_verified as preservation signals first: keep the archive and mirror intact, then run the recommended cass sources sync --json (all configured remote sources; --source narrows it) or source-specific sync command after reviewing the reported evidence.

Raw-mirror retention is explicit and audited. Use cass mirror prune --older-than 90d --json or cass mirror prune --max-size 100GB --json to get a dry-run plan; add --apply only after reviewing the scope and totals. Preview entries contain at most 1,000 manifest/blob details; omitted_entry_count reports additional candidates. Planned counts and bytes cover the entire plan, including omitted details. Use provider/path selectors to inspect a narrower scope. Previews do not append audit records. Add --keep-tag to pin captures linked to tagged conversations. prune holds down blobs referenced by captures from the last 7 days by default, writes complete intent/result records to raw-mirror/v1/pruned.jsonl for non-empty applied plans, and refuses apply mode while an index/watch job is active. Applied pruning syncs the audit independently of the optional capture setting CASS_RAW_MIRROR_FSYNC. Each completed result is recorded before the next removal; a later failure preserves those earlier results. An abrupt crash between a removal and its result record can still leave an intent without a confirmed result.

Use --provider opencode and/or --source-path '*/opencode.db' with an age or size rule to target one source without retiring unrelated captures. Repeated providers are alternatives; a source-path glob further narrows them.

A pruned capture of a source that is still on disk is copied again by the next index run. On a machine whose providers never delete their session files, set CASS_RAW_MIRROR=0 (or false, no, off) to stop capturing altogether. Indexing and search are unchanged, and existing captures stay until you prune them. cass doctor reports raw_mirror_capture_disabled and warns about what is given up: a session file its provider later deletes survives only in the archive DB. With a selector, --max-size measures unique blobs in that selection. Shared blobs still referenced outside it and orphan blobs without source provenance remain protected. The JSON plan records the selectors and scope_blob_bytes.

Large mutable sources are stored as 4 MiB content-addressed chunks. Growing JSONL files reuse every unchanged complete chunk, and SQLite sources reuse unchanged 4 MiB byte regions, so each historical snapshot remains byte-exact without writing another full-file blob. Existing whole-blob manifests remain readable; cass doctor --json reports storage_kind, chunk_count, the full-source digest, and verifies every referenced chunk before treating a snapshot as recovery authority.

Configuration File

Sources are configured in the platform config directory (Linux: ~/.config/cass/sources.toml, macOS: ~/Library/Application Support/cass/sources.toml):

[[sources]]
name = "laptop"
type = "ssh"
host = "[email protected]"
paths = ["~/.claude/projects", "~/.codex/sessions"]
sync_schedule = "manual"

[[sources]]
name = "workstation"
type = "ssh"
host = "[email protected]"
paths = ["~/.claude/projects"]
sync_schedule = "daily"

# Path mappings rewrite remote paths to local equivalents
[[sources.path_mappings]]
from = "/home/dev/projects"
to = "/Users/me/projects"

# Agent-specific mappings
[[sources.path_mappings]]
from = "/opt/work"
to = "/Volumes/Work"
agents = ["claude_code"]

Configuration Fields:

CLI Commands

# List configured sources
cass sources list [--verbose] [--json]

# Add a new source
cass sources add  [--name ] [--preset macos-defaults|linux-defaults] [--path ...] [--no-test]

# Remove a source
cass sources remove  [--purge] [-y]

# Check connectivity and config
cass sources doctor [--source ] [--json]

# Sync sessions
cass sources sync [--source ] [--no-index] [--verbose] [--dry-run] [--json]

Excluding Noisy Agent Harnesses

If one harness is generating mostly junk or looped output, you can disable it persistently even if its files remain on disk:

# Inspect current include/exclude state
cass sources agents list --json

# Stop indexing this harness in future runs
cass sources agents exclude openclaw

# Re-enable it later
cass sources agents include openclaw

cass stores this preference in sources.toml (~/.config/cass/sources.toml on Linux, ~/Library/Application Support/cass/sources.toml on macOS), so future scans, syncs, and watch-mode updates remember it automatically.

By default, cass sources agents exclude also removes already archived local data for that agent and rebuilds the lexical index so the exclusion frees space instead of only blocking future imports.

If you want to block future indexing but keep the data already archived:

cass sources agents exclude openclaw --keep-indexed-data

Sync Engine Internals

The sync engine uses rsync over SSH for efficient delta transfers and falls back to other transports when rsync is unavailable:

Transfer Methods (auto-detected):

Safety Guarantees:

• Additive-only syncs: rsync runs WITHOUT --delete, so remote deletions never propagate locally.
• Local copies follow the remote: rsync runs with -a and without -u, so a local mirror file that differs from the remote is overwritten, even when the local copy is newer. The mirror is a copy of the remote, not a place to edit sessions.
• Interrupted transfers resume: --partial keeps a partly transferred file under its final name so the next sync continues it. A failed sync can therefore leave a truncated file until the next sync completes.

Transfer Configuration:

rsync Flags Used:

-avz --links --safe-links --stats --partial [--protect-args | --secluded-args] --timeout 300 \
  -e "ssh [-F $CASS_SSH_CONFIG] -o BatchMode=yes -o ConnectTimeout=10 -o ServerAliveInterval=15 -o ServerAliveCountMax=3 -o StrictHostKeyChecking=yes"

Where -avz = archive mode + verbose + compression. --protect-args/--secluded-args is auto-detected per remote rsync version (omitted when the remote rejects it), and --timeout carries the transfer timeout in seconds. StrictHostKeyChecking=yes means a host whose key is not already in known_hosts fails with "Host key verification failed". Connect once with plain ssh and accept the key, or add it with ssh-keyscan, before the first sync.

Data Flow:

Remote: ~/.claude/projects/
    ↓ (rsync over SSH)
Local: ~/.local/share/coding-agent-search/remotes//mirror/_/
    ↓ (connector scan)
Index: agent_search.db + index/v9-quill/

Where is a filesystem-safe version of the remote path (e.g. `.claude_projects`), and is an FNV-1a hash of the original path in hex, so foo/bar and foo_bar never collide.

Sessions from remotes are indexed alongside local sessions, with provenance tracking to identify origin.

Path Mappings

When viewing sessions from remote machines, workspace paths may not exist locally. Path mappings rewrite these paths so file links work on your local machine:

# List current mappings
cass sources mappings list laptop

# Add a mapping
cass sources mappings add laptop --from /home/user/projects --to /Users/me/projects

# Test how a path would be rewritten
cass sources mappings test laptop /home/user/projects/myapp/src/main.rs
# Output: /Users/me/projects/myapp/src/main.rs

# Agent-specific mappings (only apply for certain agents)
cass sources mappings add laptop --from /opt/work --to /Volumes/Work --agents claude_code,codex

# Remove a mapping by index
cass sources mappings remove laptop 0

TUI Source Filtering

In the TUI, filter sessions by origin:

• F11: Cycle source filter (all → local → remote → all)
• Shift+F11: Open source filter menu to select specific sources

Remote sessions display with a source indicator (e.g., [laptop]) in the results list.

Provenance Tracking

Each conversation tracks its origin:

• source_id: Machine identifier (e.g., "laptop", "workstation")
• origin_kind: local or remote
• origin_host: the remote host label, absent for local sessions
• workspace_original: Original path on the remote machine (before path mapping)

--fields provenance selects exactly source_id, origin_kind and origin_host.

These fields appear in JSON/robot output and enable filtering:

cass search "auth error" --source laptop --json
cass timeline --since 7d --source remote
cass stats --by-source

🤖 AI / Automation Mode

cass is purpose-built for consumption by AI coding agents—not just as an afterthought, but as a first-class design goal. When you're an AI agent working on a codebase, your own session history and those of other agents become an invaluable knowledge base: solutions to similar problems, context about design decisions, debugging approaches that worked, and institutional memory that would otherwise be lost.

Why Cross-Agent Search Matters

Imagine you're Claude Code working on a React authentication bug. With cass, you can instantly search across:

• Your own previous sessions where you solved similar auth issues
• Codex sessions where someone debugged OAuth flows
• Cursor conversations about token refresh patterns
• Aider chats about security best practices

This cross-pollination of knowledge across different AI agents is transformative. Each agent has different strengths, different context windows, and encounters different problems. cass unifies all this collective intelligence into a single, searchable index.

Self-Documenting API

cass teaches agents how to use it—no external documentation required:

# First-stop capability contract for agents
cass triage --json
cass capabilities --json
# → {"version": "...", "workflows": [...], "mistake_recoveries": [...], "commands": [...], "exit_codes": [...], "env_vars": [...]}

# Full API schema with argument types, defaults, and response shapes
cass introspect --json

# Topic-based help optimized for LLM consumption
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 guide
cass robot-docs guide # Quick-start walkthrough

Forgiving Syntax (Agent-Friendly Parsing)

AI agents sometimes make syntax mistakes. cass aggressively normalizes input to maximize acceptance when intent is clear:

The CLI applies multiple normalization layers:

1. Typo correction: when parsing fails, long flag names within Levenshtein distance 2 of a known flag are corrected (e.g. --limt → --limit), and a first word within distance 2 of a subcommand is corrected to it (e.g. serach → search). A word that already names a subcommand is never changed, so cass status --jsn runs status --json. forget and upgrade are reached only by exact spelling.
2. Case normalization: --Robot, --LIMIT → --robot, --limit
3. Snake-case flag recovery: --max_results, --data_dir, and other known snake_case long flags become canonical kebab-case before alias recovery runs
4. Single-dash recovery: -robot → --robot (common LLM mistake)
5. Subcommand aliases: ready/preflight → triage; find/query/q/grep/lookup → search; session → sessions; answer/evidence/bundle/handoff/why/explain/rca/root-cause/rootcause/summarize/summarise → pack; html-export/html_export/exporthtml → export-html; ls/list/info/summary → stats; st/state → status; reindex/idx/rebuild → index; show/get/read → view; diagnose/debug/check → diag; caps/cap → capabilities; inspect/intro → introspect; docs/help-robot/robotdocs → robot-docs
6. Robot-docs topic shorthands: non-command topics such as commands, schemas, examples, exit-codes, and quickstart become robot-docs instead of falling through to search; command topics such as doctor and sources use structured help (cass help doctor --json, cass sources --help --json). Bare cass guide is reserved for the guided-operations planner; use cass robot-docs guide for the robot-docs walkthrough.
7. Root robot default: cass --json, cass --robot, or cass --robot-format json with no subcommand runs read-only triage
8. Leading structured flag recovery: --json/--robot before a robot-capable subcommand is moved onto that subcommand
9. Named positional recovery: --query/--q/--text/--pattern for search/pack and --path/--source-path/--file/--session for drill-down/export commands become the required positional argument
10. Multi-word query recovery: adjacent unquoted query words after search/pack become one query positional
11. Structured format recovery: --format json|jsonl|compact|sessions|toon, --output json|jsonl|compact|sessions|toon, and --output-format ... are accepted as --robot-format ... on robot-capable commands; export --format ... and export --output keep their export meanings
12. Structured help recovery: help --json, help commands --json, and search --help --json route to robot-docs guide / robot-docs commands; plain --help stays native clap help
13. Result-count aliases: --max-results, --num-results, --results, --count, --top-k, and -n become --limit on commands with result limits
14. Time-window aliases: --last 7, --before now, last=7d, and before=now become canonical --since/--until filters
15. Provider aliases: --provider, --tool, --connector, and matching assignments become canonical --agent filters on search-like commands
16. Bare option pairs: after at least one search/pack query word, provider codex, limit 5, and last 7d become canonical filter flags before the remaining words are folded into the query
17. Pack-intent recovery: a bare robot query or explicit structured-output search with pack-only flags such as --max-evidence, --max-sessions, or --freshness-policy becomes pack, not implicit or explicit search
18. Drill-down line aliases: --line-number, --line_number and line=42 become --line (a raw file line)
19. Search-hit fields: line_number=42 pasted from a search hit becomes --message-index 42 (the canonical message ordinal the hit names), and a source_path=... source_id=... line_number=... bundle becomes the canonical path, --source and --message-index form for follow-up view/expand commands
20. Leading-filter query recovery: if a search/pack query comes after leading options, the query is moved back to the required positional slot
21. Implicit robot search: unquoted top-level words with an explicit robot/JSON output request become a search query unless they look like a subcommand typo
22. Current-session shorthand: current, current-session, and sessions current become sessions --current
23. Global flag hoisting: Position-independent flag handling

When corrections are applied, cass emits a teaching note to stderr so agents learn the canonical syntax. In robot/JSON mode the same information is emitted as one note: auto-corrected: line per correction on stderr (at most two: the normalization note and the typo-recovery note), so stdout stays data-only. Robot-mode notes are printed only when the command succeeds; a failing command's stderr is its single JSON error envelope. The same notes appear in search output under _meta.effective.auto_corrections with --robot-meta.

Structured Output Formats

Every command supports machine-readable output:

# Pretty-printed JSON (default robot mode)
cass search "error" --robot

# Streaming JSONL: one hit per line. Add --robot-meta to prepend a
# {budget, _meta} header line (elapsed_ms, next_cursor, state, index_freshness).
# The header also appears without --robot-meta when the search timed out
# (budget.timed_out), returned did-you-mean suggestions, --aggregate or --explain.
cass search "error" --robot-format jsonl               # hits only
cass search "error" --robot-format jsonl --robot-meta  # 1 _meta header + hits

# Compact single-line JSON (minimal bytes)
cass search "error" --robot-format compact

# Include performance metadata
cass search "error" --robot --robot-meta
# → { "hits": [...], "_meta": { "elapsed_ms": 12, "cache_hit": true, "wildcard_fallback": false, "lexical_degrade_reason": null, ... } }
#   lexical_degrade_reason is "query_fuel_exhausted" when a hybrid search dropped its
#   lexical leg because Quill's query fuel ran out (see CASS_QUILL_QUERY_FUEL_BUDGET)

# What the search actually ran (--robot-meta): check this instead of trusting the flags
cass search "error" --robot --robot-meta --days 7 | jq '._meta.effective'
# → { "command": "search", "query": "error",
#     "query_structure": "error",           // how the engine groups operands: `a OR b c` -> "a OR (b AND c)"
#     "query_recoveries": [],               // e.g. "1 unclosed '(' closed at the end of the query"
#     "db_path": "/home/you/.local/share/coding-agent-search/agent_search.db",
#     "db_path_source": "default",          // --db | env:CASS_DB_PATH | --data-dir | env:CASS_DATA_DIR | env:XDG_DATA_HOME | default
#     "time_window": { "since_ms": 1758067200000, "since_from": "--days 7", "until_ms": null, "until_from": null },
#     "filters": { "agents": [], "workspaces": [], "source": "all", "sessions_from_paths": null },
#     "auto_corrections": [] }              // each argv correction, worded like its stderr note
#   `cass pack "error" --json` carries the same object for the search it ran in
#   its own `_meta.effective` ("command": "pack", and no search-only "daemon"),
#   with home-directory paths, private hosts and secrets redacted like the rest
#   of the pack (the db_path above reads "[REDACTED_PATH]/agent_search.db").

# Per-hit trust verdict (advisory; --robot-meta only)
cass search "error" --robot --robot-meta
# Each hit then carries a metadata-only `trust` block:
#   "trust": {
#     "schema_version": 1,
#     "trust_tier": "unverified",     // trusted | likely | unverified | stale | failed
#     "confidence": "medium",         // low | medium | high
#     "provenance_refs": [],          // e.g. ["commit:ab0d12ef90ab", "bead:xyz", "release:v0.6.15"]
#     "stale_reason": "aged_out",     // present only when not fully trusted
#     "recommended_followup": "..."   // advisory next step (never a destructive command)
#   }

How agents should branch on trust_tier (relevance is not correctness — a hit can be a landed fix or a failed attempt):

The verdict is advisory metadata only — it never changes result ordering. It is derived from metadata-only signals (recency, source health, realized search mode, cwd-relative workspace match, and — opportunistically — linked commit/bead/release provenance); it carries no raw session text. The same trust block is attached to cass pack evidence. Branch on trust_tier and stale_reason, not on confidence alone.

Provenance correlation is project-scoped and explicit-reference anchored: for a hit from the project you are running cass in now, cass links it to a closed bead or commit only when the hit's own indexed text references a known identifier (bead: or commit:), joined against that project's local beads and git history. A linked commit's containing release is resolved from Git. Release containment preserves provenance but does not establish proof of the excerpt's claim: a landed commit remains proof_debt and cannot become trusted from this correlation alone. A temporal or workspace coincidence is never enough, so an unrelated conversation never inherits another's trust. Off-project hits report workspace_mismatch, and a hit whose local source file no longer exists on disk reports source_unhealthy (archive-only) instead of overtrusting a dead path.

# Deterministic answer pack for handoff prompts
cass pack "why did checkout fail" --robot --max-tokens 12000 --limit 40

# Freshness-sensitive pack: fail if selected evidence is outside the window
cass pack "checkout timeout after redirect" --robot \
  --freshness-policy strict --freshness-window-seconds 604800 \
  --max-tokens 12000 --require-evidence

# Token-budgeted pack for pasting into another agent
cass pack "checkout timeout after redirect" --robot \
  --max-tokens 4000 --max-evidence 8 --max-sessions 3 --max-excerpt-chars 600

# Pipeline from broad search to a bounded cited handoff
cass search "checkout timeout" --robot-format sessions \
  | cass pack "checkout timeout root cause" --robot --sessions-from -

Design principle: stdout contains only parseable JSON data; all diagnostics, warnings, and progress go to stderr.

Use search when you are still exploring candidate sessions. Use pack when you need a compact, cited, extractive artifact to hand to another agent or a human operator. Use status/health before trusting freshness-sensitive output, and use doctor only for diagnostics or safe repair workflows. Use export-html when you need a full browsable session archive; packs are token-budgeted evidence bundles, not full exports and not external summarization.

Pack robot output includes health, freshness, privacy, and warnings. Warnings such as privacy_redactions_applied, semantic_fallback_lexical, or no_evidence_found are data, not prose; branch on the JSON fields before copying the pack into another tool. Stale selected evidence is structural: inspect freshness.stale_evidence_count.

Packs exclude injected skill payloads by default. Add --include-skill-content to include them explicitly; credential redaction still applies. privacy.skill_content_included reports whether the selected evidence includes skill payloads, including after token-budget trimming.

Swarm Operations Workflow

Use the swarm surfaces when multiple agents are sharing one repo and you need a single read-only view before claiming work:

# Current shared-work snapshot; does not claim, reopen, release, or run builds
cass swarm status --json

# Advisory packet for one bead; still create real reservations and Beads updates yourself
cass swarm work-packet --json --bead coding_agent_session_search-example

# Coordination hygiene check before closeout or takeover review
cass swarm lint --json --bead coding_agent_session_search-example

# Read-only sibling dependency drift sentinel
cass swarm dependency-drift --json

swarm status, swarm work-packet, swarm lint, swarm evidence, swarm proof-debt and swarm failure-patterns collect the same bounded read-only Git state and Beads exports when run from the repository root without a fixture. Git uses porcelain-v2 with optional locks disabled. Beads uses br 0.6.x --no-db, so its JSONL snapshot is explicitly partial: unexported database changes may exist. Recheck Beads and reservations before claiming work. Child commands share a single 15-second request budget and each has an 8 MiB output cap; Beads categories cap at 512 issues. Failures report unavailable providers and unknown summary counts, not zero work. RCH contributes aggregate active/queued job counts, fleet slots and posture from rch status --json (API 1.0, schema 1.0.0). Responses older than 60 seconds or more than 5 seconds in the future are unavailable. Worker addresses, commands and job details are omitted. This provider remains partial: local Cargo/CPU state and build admission are unknown, even when RCH reports no active jobs. Agent Mail roster and reservation reads are opt-in: set CASS_SWARM_AGENT_MAIL_URL to the server's HTTP MCP endpoint and, if required, CASS_SWARM_AGENT_MAIL_TOKEN. The reader uses only resources/read, never a local database fallback or inbox read. Mail shares the total request budget with a 3-second cap of its own; responses are capped at 8 MiB, rosters at 512 agents, and full 250-row reservation pages are refused. The total reservation count remains unknown; source metadata reports only the observed active count. Activity and expiry use the observation time. Task descriptions, reservation reasons and message bodies are omitted. These observations do not authorize claims or establish proof. CASS evidence remains unwired. Live lint marks itself partial and adds an agent-mail-unavailable advisory whenever Agent Mail messages are not collected. Fixture selection (--fixture or --fixture-dir --fixture-id ) retains deterministic behavior; swarm dependency-drift also has a live path.

swarm status composes Beads, Agent Mail metadata, git state, rch/build pressure, cass health/status, and proof references. Stale candidates are advisory only: coordinate through Beads and Agent Mail before reopening, force-releasing, or taking over work. Suggested commands are robot-safe templates, not automatic actions.

The TUI's Swarm tab shows the same live payload for the directory the TUI was started in. Open it from the command palette (Ctrl+P, "Swarm operations cockpit") or by clicking its tab; it has no direct key. Entering the tab starts one background read with this collector; until it lands, every count shows as ?. Counts of providers that could not be read stay ?, never zero. r reads again. Rendering never runs a provider read.

swarm dependency-drift reads Cargo.toml and optional sibling checkouts to report manifest pins, local HEAD/dirty state, strict validation commands, and release-risk recommendations. It does not fetch remotes, edit manifests, run builds, update Beads, send Agent Mail, delete files, or mutate git state.

When status points at prior evidence, use cass pack "query" --robot to create a bounded cited handoff for another agent. Packs complement the cockpit; they do not replace Beads for ownership, Agent Mail for coordination, or rch for proof commands.

Token Budget Management

LLMs have context limits. cass provides multiple levers to control output size:

Truncated fields include a *_truncated: true indicator so agents know when they're seeing partial content.

Contributor verification for docs or contract changes should use rch, for example:

rch exec -- env CARGO_TARGET_DIR=${TMPDIR:-/tmp}/rch_target_cass_answer_pack_docs \
  cargo test --test golden_robot_docs

Error Handling for Agents

Errors are structured, actionable, and include recovery hints. A real sample from cass search foo --robot against a fresh data dir:

{
  "error": {
    "code": 3,
    "kind": "missing-index",
    "message": "cass has not been initialized in  yet, so search cannot run until the first index completes.",
    "hint": "Run 'cass index --full' once to discover local sessions and build the initial archive.",
    "retryable": true
  }
}

Kind names are kebab-case (e.g. missing-index, missing-db, semantic-unavailable, embedder-unavailable, ambiguous-source, timeout, config, lock-busy). Agents that branch on err.kind should treat them as stable identifiers. The full set (about 90 kinds) is defined in src/model/cli_error_kind.rs; the canonical way to discover a kind programmatically is to trigger the condition and inspect err.kind from the JSON envelope.

Exit codes follow a semantic convention:

Search/pack timeouts are not exit 8: on expiry search and pack exit 0 with {"hits": [], "budget": {"timed_out": true, "skipped_sections": [...], "recommended_next_probe": "", ...}}, and --robot-format sessions instead fails with exit 10, kind timeout. Explicit --mode semantic is the other exception: when the remaining budget cannot admit semantic setup or dispatch, search fails with exit 10, kind timeout, retryable: true, and a semantic_budget checkpoint=... message, rather than returning an empty or lexical result. Hybrid (explicit or default) instead falls back to lexical and reports semantic_budget_limited.

Codes ≥ 10 are domain-specific and the numeric value alone is ambiguous (e.g. code 10 maps to either config or timeout kinds depending on context). Agents should branch on err.kind from the JSON error envelope — not on the numeric code — when handling codes ≥ 10. See the Error Handling section above for the canonical kind list.

The retryable field tells agents whether a retry might succeed (e.g., transient I/O) vs. guaranteed failure (e.g., invalid path). A lexical query the engine refuses with posting cursor invariant failed (kind search, exit 9) is retryable: false: the same query fails the same way on the same index generation. The hint names the remedy, cass index --full --force-rebuild. Date-filtered searches over an index segment that holds deleted rows triggered it before frankensearch-quill 0.3.2 (GH #499).

Session Analysis Commands

Beyond search, cass provides commands for deep-diving into specific sessions:

# Discover the current session for this workspace
cass sessions --current --json

# List recent sessions for a specific project
cass sessions --workspace /path/to/project --json --limit 5

# Export full conversation to shareable format
cass export /path/to/session.jsonl --format markdown -o conversation.md
cass export /path/to/session.jsonl --format json --include-tools

# Export as self-contained HTML with encryption (recommended for sharing)
cass export-html /path/to/session.jsonl                     # To Downloads folder
printf '%s\n' "pwd" | cass export-html session.jsonl --encrypt --password-stdin
cass export-html session.jsonl --open --json                # Open in browser, JSON output

# Common agent flow: find current session, then export it
cass export-html "$(cass sessions --current --json | jq -r '.sessions[0].path')" --json

# Expand context around a specific line (from search result)
cass expand /path/to/session.jsonl -n 42 -C 5 --json
# → Shows 5 messages before and after line 42

# Activity timeline: when were agents active?
cass timeline --today --json --group-by hour
cass timeline --since 7d --agent claude --json
# → Grouped activity counts, useful for understanding work patterns

Aggregation & Analytics

Aggregate search results server-side to get counts and distributions without transferring full result data:

# 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 Fields:

Response Format:

{
  "aggregations": {
    "agent": {
      "buckets": [
        {"key": "claude_code", "count": 120},
        {"key": "codex", "count": 85}
      ],
      "other_count": 15
    }
  }
}

Top 10 buckets are returned per field, with other_count for remaining items.

Bounded incident mining

Mine recurrent CASS operational incidents from the canonical archive without dumping raw session text:

cass analytics incidents --limit 10 --json

# Tighten the bounded scan for automation or a very large archive
cass analytics incidents --max-sessions 500 --max-messages 50000 \
  --max-bytes 67108864 --budget-ms 5000 --json

The response ranks top_sessions[] by hit count and category breadth and keeps the exact conversation_id, agent, host, source_id, source_path, live/archive state, dominant categories, and a structured cass view argv. That argv carries the effective --db path plus --conversation-id, so it opens the exact ranked archive row even when multiple sessions share a source path or the report used a non-default database. total_sessions, total_hits, and top_sessions_truncated distinguish the bounded ranked result from the totals observed inside the scan scope. discovery.partial and stop_reason explicitly distinguish a bounded partial scan from a complete scan. Counts are scoped to scanned candidates whenever the scan is partial. --budget-ms is a hard wall-clock result guard around the independently row-bounded read-only worker. If it expires before a verified result arrives, count_scope="no_verified_results_hard_timeout" returns an empty partial report instead of overstating in-flight observations. Candidate discovery is descending archive-row keyset paging; --max-sessions bounds that newest-row window before dimensional filters, so a selective filter can truthfully return a partial empty result instead of scanning an unbounded archive. Individual messages are inspected through a bounded 4,096-char fragment; an oversized message returns message-fragment-capped rather than claiming a complete corpus scan. Raw prompt/tool content is always suppressed; evidence carries only BLAKE3 fingerprints and basename-redacted paths. The actionable source_path remains visible solely so the returned view command works.

Chained Search (Pipeline Mode)

Chain multiple searches together by piping session paths from one search to another:

# Find sessions mentioning "auth", then search within those for "token"
cass search "authentication" --robot-format sessions | \
  cass search "refresh token" --sessions-from - --robot

# Build a filtered corpus from today's work
cass search --today --robot-format sessions > today_sessions.txt
cass search "bug fix" --sessions-from today_sessions.txt --robot

How It Works:

1. First search with --robot-format sessions outputs one session path per line
2. Second search with --sessions-from restricts search to those sessions
3. Use - to read from stdin for true piping

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

Match Highlighting

Snippets always mark the terms the search engine matched with **bold**, in human-readable output and in robot/JSON output alike. The --highlight flag also marks the query terms' remaining literal occurrences and leaves already-marked text alone, so no term gets two pairs of marks. Only the snippet field is marked; content stays verbatim:

cass search "authentication error" --robot --highlight
# "snippet": "... **authentication** failed with **error** ..."

Highlighting is query-aware: quoted phrases like "auth error" highlight as a unit; individual terms highlight separately.

Pagination & Cursors

For large result sets, use cursor-based pagination:

# First page
cass search "TODO" --robot --robot-meta --limit 20
# → { "hits": [...], "_meta": { "next_cursor": "eyJ..." } }

# Next page
cass search "TODO" --robot --robot-meta --limit 20 --cursor "eyJ..."

A cursor is base64 JSON {"offset": N, "limit": M}: a plain page position, not a snapshot. Any index change between pages (a new session indexed, a rebuild, a forget) shifts the ranking, so the next page can skip or repeat hits. Page quickly, or fix the window with --until when you need stable pages.

Match Counts: Exact or Lower Bound

total_matches answers "how many messages match?", but it is exact only when cass can afford to count. Every search fetches one hit beyond --limit to learn whether another page exists. When the page is full and the index is larger than CASS_SEARCH_EXACT_TOTAL_COUNT_MAX_DOCS documents, cass skips the full count and reports that limit + 1 as a lower bound. Below the threshold it counts every match.

--robot-meta says which kind of number you got:

cass search "stale lock" --robot --robot-meta --limit 10 \
  | jq '{total_matches, precision: ._meta.cursor_manifest.count_precision, why: ._meta.cursor_manifest.count_reason}'
# → {"total_matches": 11915, "precision": "exact", "why": "total_matches is exact; no extra recount was needed"}
# A lower bound reads "precision": "lower_bound".

Why the threshold moved. The 50,000 cap dates from the Tantivy engine, where counting a common term over millions of documents could dominate the query. The Quill engine counts cheaply. Paired runs on that 1,034,219-document archive, capped against exact (--limit 10, read-only, CPU time):

Each search cost about 0.8 s of CPU either way. The capped answer, meanwhile, was wrong by up to five orders of magnitude, and agents read total_matches as a count. The default now covers five times that archive; set CASS_SEARCH_EXACT_TOTAL_COUNT_MAX_DOCS=0 to never count exactly, or raise it for a larger archive.

Aggregations have their own window. --aggregate buckets are computed over the top max(1000, limit + offset) hits, so bucket counts on a large archive describe the best-ranked thousand matches, not the whole corpus. Use an exact total_matches for "how many", and aggregations for "how are the top hits distributed".

Request Correlation

For debugging and logging, attach a request ID:

cass search "bug" --robot --request-id "req-12345"
# → { "request_id": "req-12345", "hits": [...], ... }
#   (top level always; also under _meta.request_id with --robot-meta)

Idempotent Operations

For safe retries (e.g., in CI pipelines or flaky networks):

cass index --full --idempotency-key "build-$(date +%Y%m%d)"
# If same key + params were used in last 24h, returns cached result

Query Analysis

Debug why a search returned unexpected results:

cass search "auth*" --robot --explain
# → Adds "explanation": the sanitized query, flat lists of its terms, phrases and
#   operators (not a tree), the query type and index strategy, a low/medium/high cost
#   class, a filter summary and warnings. Wildcards are reported, not expanded.

cass search "auth error" --robot --dry-run
# → Validates query syntax without executing

Traceability

For debugging agent pipelines:

cass search "error" --robot --trace-file /tmp/cass-trace.json
# Appends execution span with timing, exit code, and command details

cass index --full --json --robot-trace-ingest 2>/tmp/cass-ingest-trace.jsonl
# Streams one NDJSON record per ingest batch with wall_ms, batch_msgs,
# inserted_messages, and duplicate-lookup counters for perf bisects

Search Flags Reference

Index Flags Reference

When health --json or status --json reports index.status: "hollow", the live Quill generation serves fewer than half the documents certified by its completed rebuild checkpoint. index.live_documents reports the served count. Run cass index to let its pre-scan repair rebuild from the canonical archive; cass index --full also rescans the session sources. A missing count provides no hollow-generation verdict.

Robot Documentation System

For machine-readable documentation, use cass robot-docs :

# Get documentation programmatically
cass robot-docs guide
cass robot-docs schemas
cass robot-docs exit-codes

# Machine-first help (wide output, no TUI assumptions)
cass --robot-help

API Contract & Versioning

cass maintains a stable API contract for automation:

cass api-version --json
# → { "crate_version": "", "build_commit": "", "api_version": 1, "contract_version": "1" }

cass introspect --json
# → Full schema: all commands, arguments, response types

Contract Version: Currently 1. Increments only on breaking changes.

Guaranteed Stable:

• Exit codes and their meanings
• JSON response structure for --robot output
• Flag names and behaviors
• _meta block format

Ready-to-paste blurb for AGENTS.md / CLAUDE.md

🔎 cass — Search All Your Agent History

 What: cass indexes conversations from Claude Code, Codex, Cursor, Gemini, Aider, ChatGPT, and more into a unified, searchable index. Before solving a problem from scratch, check if any agent already solved something similar.

 ⚠️ NEVER run bare cass — it launches an interactive TUI. Always use --robot or --json.

 Quick Start

 # One-shot agent triage (read next_command when present)
 cass triage --json

 # Search across all agent histories
 cass search "authentication error" --robot --limit 5

 # Build a cited handoff pack from search evidence
 cass pack "authentication error root cause" --robot --max-tokens 12000 --limit 40

 # Tight handoff budget with freshness and privacy metadata
 cass pack "authentication error root cause" --robot --max-tokens 4000 --max-evidence 8 --fields summary

 # View a specific result (from search output)
 cass view /path/to/session.jsonl -n 42 --json

 # Expand context around a line
 cass expand /path/to/session.jsonl -n 42 -C 3 --json

 # Learn the full API
 cass capabilities --json # Static agent self-description
 cass robot-docs guide # LLM-optimized docs

 Why Use It

 - Cross-agent knowledge: Find solutions from Codex when using Claude, or vice versa
 - Forgiving syntax: Typos and wrong flags are auto-corrected with teaching notes
 - Token-efficient: --fields minimal returns only essential data; pack budgets cite only selected evidence
 - Copy-safe handoffs: pack warnings include freshness and privacy/redaction status

 Key Flags

 | Flag | Purpose |
 |------------------|--------------------------------------------------------|
 | --robot / --json | Machine-readable JSON output (required!) |
 | --fields minimal | Reduce payload: source_path, line_number, agent, source_id, conversation_id |
 | pack --max-tokens N | Budget a cited handoff pack |
 | --limit N | Cap result count |
 | --agent NAME | Filter to specific agent (claude, codex, cursor, etc.) |
 | --days N | Limit to recent N days |

 stdout = data only, stderr = diagnostics. Exit 0 = success.

🔤 Query Language Reference

cass supports a rich query syntax designed for both humans and machines.

Basic Queries

Boolean Operators

Combine terms with explicit operators for complex queries:

Operator Precedence: NOT binds tightest, then AND (explicit, &&, or implied between words), then OR (OR, ||). Parentheses group, in the TUI and robot mode alike: a OR b c means a OR (b AND c), while (a OR b) c needs the parentheses. A ( groups only at the start of a word, so code such as foo(bar) stays one term. NOT NOT x is x. Unbalanced parentheses are recovered rather than rejected. The SQLite fallback lanes, used while no lexical index is available, apply the same grammar.

# Complex boolean query
cass search "authentication AND (error OR failure) NOT test" --robot

# Exclude test files
cass search "bug fix -test -spec" --robot

# Either error type
cass search "TypeError OR ValueError" --robot

Phrase Queries

Wrap terms in double quotes for exact phrase matching:

Phrases match their words adjacent and in order (no slop). Useful for error messages, code patterns, and specific terminology.

Wildcard Patterns

Tip: Prefix wildcards (foo*) use edge n-grams computed at index time: prefixes of 2–20 characters of every alphanumeric word, taken from titles and from the first 4 KiB of each message. Suffix and substring wildcards expand over the index's term dictionary, at most 16,384 terms per pattern; a pattern matching more terms fails rather than scanning. The tokenizer splits on anything that is not a letter or digit: test_* is a prefix match on test, c++ searches for c, and foo.bar means foo AND bar anywhere in the message, not the literal string. Phrases ("...") match adjacent words in order (slop 0).

Query Modifiers

# Field-specific search (in robot mode)
cass search "error" --agent claude --workspace /path/to/project

# Time-bounded search
cass search "bug" --since 2024-01-01 --until 2024-01-31
cass search "bug" --today
cass search "bug" --days 7

# Combined filters
cass search "authentication" --agent codex --workspace myproject --week

Flexible Time Input

cass accepts a wide variety of time/date formats for filtering:

Intelligent Heuristics:

• Numbers of 100,000,000,000 (10^11) or more are milliseconds; smaller numbers are seconds
• Years are written in full (2024, not 24)
• A value that names a whole day (a date without a time, today, yesterday) starts at local midnight as --since and runs through the day's last millisecond as --until, so --until 2024-01-31 includes January 31
• For search and pack, a --since/--until value that cannot be parsed, or a --since later than --until, is a usage error (exit 2, kind usage); it is never silently ignored

# All equivalent for "last week"
cass search "bug" --since -7d
cass search "bug" --since "-1w"
cass search "bug" --days 7

# Date range
cass search "feature" --since 2024-01-01 --until 2024-01-31

# Mix formats
cass search "error" --since yesterday --until now

Match Types

Search results include a match_type indicator. It describes the query, not each hit: every hit of a search carries the type of the least precise pattern in the query (e.g. auth* *tion stamps suffix on all hits).

Relevance scores carry no boost for the match type; only the TUI's Match Quality ranking mode (F12) orders by it.

Auto-Fuzzy Fallback

When an exact query's first page returns fewer than 3 results (or fewer than a smaller --limit), cass retries with wildcard expansion:

• auth → *auth*
• It runs only on indexes with at most 10,000 documents (CASS_AUTOMATIC_WILDCARD_FALLBACK_MAX_DOCS; 0 disables it), so on a typical real archive it does not run.
• It skips queries that already use wildcards, boolean operators or phrases, and zero-hit queries containing a token longer than 16 characters.
• The wildcard results replace the exact ones only when they find more hits; robot mode then reports _meta.wildcard_fallback: true. When a sparse result did not get the retry, _meta.wildcard_fallback_skipped says why: index_over_automatic_limit (the index is over the document cap), automatic_retry_disabled (the cap is 0) or long_query_term; add explicit wildcards to run it anyway
• TUI shows a "fuzzy" indicator in the status bar

⌨️ Complete Keyboard Reference

Global Keys

Launch-time flags: cass tui --refresh (alias --catch-up) runs an incremental index pass before opening; --record-macro FILE / --play-macro FILE record and replay input events.

Search Bar (Query Input)

Navigation

Filtering

Modes & Display

For one chronological list across agents, select flat grouping with Alt+F and newest ranking with F12. Grouping is also available in the command palette and is preserved with ranking and filters in saved views.

Selection & Actions

Detail Pane

These apply while the detail modal is open:

Detail Tabs

The detail pane has six tabs, cycled with Tab:

Context Window Sizing

Control how much content shows in the detail preview. Cycle with F7:

Peek Mode (Ctrl+Space): Temporarily expand to XL context. Press again to restore previous size. Useful for quick deep-dives without changing your preferred default.

Mouse Support

• Click on result to select
• Click on filter chip to edit/remove
• Scroll in any pane
• Double-click to open result

Bulk Operations

Efficiently work with multiple search results at once:

Multi-Select Mode:

1. Press Ctrl+X to toggle selection on current result (checkbox appears)
2. Navigate to other results and press Ctrl+X again
3. Press Ctrl+A to select/deselect all visible results
4. Selected count shown in footer: "3 selected"

Bulk Actions Menu (Alt+B when items selected):

Multi-Open Queue: For opening many files without navigating away:

1. Press Ctrl+Enter to add current result to queue
2. Continue searching and adding more results
3. Press Ctrl+O to open all queued items
4. Confirmation prompt appears for 12+ items

Clipboard Operations:

• Ctrl+Y - Copy the current item's path
• Alt+Y - Copy the current item's snippet
• Ctrl+Shift+C - Copy the current item's content
• Bulk actions menu → Copy Paths for every selected item

📊 Ranking & Scoring Explained

The Six Ranking Modes

Cycle through modes with F12 (or Alt+R) in the TUI. The search engine returns hits in its own relevance order; the mode then re-orders the results the TUI has loaded (the first page of up to 250 hits, plus every further page you load), so the whole loaded list always follows one order. Ranking modes are TUI-only; robot search returns engine order.

1. Recent Heavy: Score = relevance × 0.3 + recency × 0.7. Best for: "What was I working on?"

2. Balanced (default): Score = relevance × 0.5 + recency × 0.5. Best for general-purpose search.

3. Relevance: Score = relevance × 0.8 + recency × 0.2. Best for "find the best explanation of X".

4. Match Quality: exact matches first, then prefix, suffix, subs