coding-agent-session-search

🔎 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, Oh My Pi, GitHub Copilot Chat, Copilot CLI, OpenClaw, Clawdbot, Vibe, Crush, Goose, Hermes, Kimi Code, Muse Code, Qwen Code, Factory (Droid), Antigravity, OpenHands, and Grok Build 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 <tag> / -Version <tag> 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 <dir>. 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 <data_dir>/index/.lexical-publish-backups/<dated>/ 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 on the next startup, which moves any orphaned canonical sidecar (.<name>.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 artifact (failed seed bundles, retained publish backups, quarantined lexical generations) 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 <data_dir>/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

• The JSON contract surfaces (triage, capabilities, selftest, health, status, diag, models status, models verify, models check-update, introspect, doctor, api-version, stats, sessions, search, pack, swarm status, swarm work-packet, swarm lint) are pinned by golden-file regression tests under tests/golden/robot/. 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)