Dicklesworthstone/coding_agent_session_search

🔎 coding‑agent‑search (cass) – a unified, high‑performance TUI for your local AI‑coding‑assistant history

What it is – cass is a Rust‑based command‑line / terminal‑UI tool that gathers the conversation logs of dozens of popular coding agents (Claude Code, GitHub Copilot Chat, Cursor, Aider, etc.), normalises them into a common JSON schema, stores everything in a local SQLite archive, and lets you search that archive instantly. It works entirely offline; any optional semantic search runs on‑device with a tiny MiniLM model you explicitly install.

---

📦 Installation

• One‑liner script (Linux/macOS/Windows PowerShell) that fetches the latest release and verifies the binary.
• Homebrew tap (brew install dicklesworthstone/tap/cass) – pre‑built tarballs for Linux and Apple‑Silicon macOS.
• Scoop bucket for Windows.
• Packages can also be pinned to a specific version with --version <tag>.

---

🚀 Quick “robot” (machine‑readable) workflow

Step	Command	What it does
1	cass triage --json	Checks the archive health and tells an agent what to do next (next_command, recommended_commands, etc.).
2	cass search "…" --robot --limit 5 --fields minimal	Runs a hybrid search (fast lexical + optional MiniLM refinement) and returns JSON results suitable for automation.
3	cass sessions --current --json	Finds the most recent session for the current workspace.
4	cass view <session>.jsonl -n 42 --json	Retrieves a single message (line 42) from a stored session.
5	cass capabilities --json	Lists the full machine‑API surface (triage, search, models, doctor, …).
6	cass sources agents exclude openclaw	Stops a noisy agent from being indexed in the future.

All robot commands emit only data on stdout and diagnostics on stderr, with exit‑code 0 on success.

---

✨ Key features (plain‑language)

• Cross‑agent aggregation – pulls logs from >30 different coding assistants and puts them in one searchable timeline.
• Instant lexical search – edge‑ngram indexing gives sub‑60 ms query latency even on a 10 GB archive.
• Optional semantic search – after cass models install you get MiniLM‑based vector search, still offline, with a fallback to pure lexical results when the model isn’t present.
• Atomic, crash‑safe indexing – each lexical publish is an atomic rename; a backup of the previous generation is kept for one‑step rollback.
• Robust diagnostics – cass doctor and cass diag enumerate quarantined assets, suggest safe clean‑up actions, and can apply proven fixes automatically.
• Stable JSON contracts – every robot‑mode output follows a versioned schema that is guarded by golden‑file tests, making it safe for downstream automation.
• Air‑gapped operation – you can bring your own MiniLM files (--from-file) and never need network access after installation.
• Extensible “robot” mode – the tool can be called from other agents (e.g., an LLM‑driven workflow) to retrieve relevant past conversations as context.

---

🛠️ How it works under the hood (high‑level)

1. Ingestion – a background indexer reads the various agent‑specific log formats, converts each message to a unified JSON record, and writes it into a SQLite database.
2. Lexical index – a custom full‑text engine (based on Tantivy) builds edge‑ngram indexes for fast prefix matching.
3. Semantic vectors – when a MiniLM model is installed, each message is embedded and stored in a Frankensearch FSVI vector file; a daemon can serve these embeddings for reuse across searches.
4. Hybrid query – a search first returns lexical hits, then (if a model is present) refines the ranking with cosine similarity on the vectors.
5. Atomic publishing – new lexical generations are swapped atomically; any interrupted publish is recovered on the next start‑up.

---

👥 Who benefits

• Solo developers who switch between Copilot, Cursor, Claude, etc., and need to recall a past solution without digging through many files.
• Teams that want a shared, privacy‑preserving knowledge base of all coding‑assistant interactions.
• AI‑agent pipelines that can call cass in robot mode to enrich their own context with historical answers.
• Power users who want to script custom analytics (e.g., token‑usage stats) on top of a stable JSON API.

---

📚 Further reading

• Screenshots – three‑pane TUI with colour‑coded agents, markdown‑rendered conversation view, and built‑in help screen.
• Design docs – the README explains the lexical publish durability model, quarantine/GC policy, and the exact error‑envelope schema.
• Model details – all‑minilm‑l6‑v2 (90 MB) for English, multilingual‑minilm (480 MB) for CJK/mixed text.

---

✅ Bottom line

cass gives you a fast, offline, cross‑agent search engine for every AI‑coding‑assistant you’ve ever used, with a robust CLI/JSON interface that lets other tools (or the agents themselves) tap into that knowledge base. It’s built in Rust, ships as a single binary, and keeps all data on your machine—no telemetry, no cloud calls.