cass (coding-agent-search): One Search Index Over Every Coding Agent's Session Logs

The problem cass solves: session history scattered across a dozen harnesses

Every coding agent writes its own transcript in its own format, in its own directory, with its own idea of what a message is. Codex, Claude Code, Gemini CLI, Cline, OpenCode, Amp, Cursor, ChatGPT, Aider, Copilot Chat, Goose, Qwen Code and the rest each keep a local record, and none of them can search the others. If you have used three or four of them over a year, the answer to "where did I fix that auth bug" is spread across four incompatible stores you can only query one at a time.

cass is aimed at that specific gap. The README describes it as a unified TUI to index and search local coding agent history, aggregating sessions from a long list of providers into a single searchable timeline. The audience is developers who switch harnesses, and, judging by the README's robot-mode section, the secondary audience is other agents: cass is designed to be driven headlessly by an AI coding agent that needs to recall what a previous session did.

It is not a cloud service and it is not a transcript viewer bolted onto one product. The unit of work is your local archive, indexed in place.

How the index works: SQLite as source of truth, lexical as the required path

The README states a clear contract: SQLite is the source of truth for indexed conversations and messages, and every derived asset (the lexical index, semantic vectors, analytics rollups, retention backups) can be rebuilt from it. No derived asset is authoritative. That single sentence explains most of the tool's operational behaviour, including why it prefers to rebuild rather than ask you to repair something by hand.

Search runs in two layers. Lexical search is the required fast path and always available. Semantic search is opportunistic background enrichment, and hybrid is the default intent. When semantic assets are not ready, results are lexical-only and the robot metadata reports a fallback reason. The README lists the expected cases for lexical-only output: first indexing, semantic catch-up, a disabled semantic policy, or missing local model and vector files. This is a sensible ordering. It means the tool is useful the moment indexing finishes, and the vector layer is a quality upgrade rather than a precondition.

The lexical publish path is the most carefully described mechanism in the README. Each publish is an atomic renameat2(RENAME_EXCHANGE) on Linux, or a parked-rename with restore-on-failure elsewhere, so readers see either the old generation or the new one and never a half-written index. The prior live generation is retained under <data_dir>/index/.lexical-publish-backups/<dated>/, capped at one generation by default for one-step rollback. The CASS_LEXICAL_PUBLISH_BACKUP_RETENTION environment variable overrides that cap, with 0 disabling retention. A crash between the swap and the retain rename is handled at next startup by recover_or_finalize_interrupted_lexical_publish_backup, which moves an orphaned .<name>.publish-in-progress.bak sidecar into the backups directory before the next publish.

That is more machinery than most search tools bother with, and it points at a real constraint: the index is large and rewritten often, so torn reads and interrupted publishes are the failure modes that matter. Corrupt artifacts are quarantined rather than deleted, and cass diag --json --quarantine enumerates them with size_bytes, age_seconds, safe_to_gc and a gc_reason. The README is explicit that safe_to_gc is advisory and not wired to any deletion path, which is the right call for a tool holding the only copy of your session archive.

Installing cass and running a first search

The README offers an install script for Unix and PowerShell, plus Homebrew and Scoop packages. The script installs the latest release by default and takes a version flag to pin a tag. The Homebrew tap installs prebuilt release tarballs rather than bottles for Linux and Apple Silicon macOS; on Intel macOS the README says to use the install script with --from-source.

On Linux or macOS, the documented one-liner is:

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

The --verify flag is worth keeping. After it finishes, the README gives a way to confirm the binary without touching your archive:

cass selftest --json

The README notes that health --binary-only still probes archive readiness, so selftest is the narrower check if you only want to know the executable works.

Before any real query, the README warns in bold that you must never run bare cass in an agent context, because it launches the interactive TUI. Use the robot or JSON flags instead. The recommended first command is triage, which returns readiness, a next_command field, recommended commands, docs pointers and accepted recoveries:

cass triage --json

For a human at a terminal, the same binary opens the TUI when run without flags. For a scripted search across everything indexed, the README's example is:

cass search "authentication error" --robot --limit 5 --fields minimal

Output conventions are stated plainly: stdout carries data only, stderr carries diagnostics, and exit 0 means success. To see the surrounding context of a hit, search output gives you a source_path and line_number, which feed view and expand:

cass view /path/to/session.jsonl -n 42 --json
cass expand /path/to/session.jsonl -n 42 -C 3 --json

If one harness floods your index, the sources subcommand manages inclusion. The README's example excludes a noisy harness and can reverse it:

cass sources agents list --json
cass sources agents exclude openclaw
cass sources agents include openclaw

Semantic search is not installed by default. The README says model acquisition is opt-in and that cass never auto-downloads or auto-selects the multilingual space. The command is cass models install, which fetches the default all-minilm-l6-v2 (alias minilm, about 90 MB), while --model multilingual-minilm selects the larger MiniLM L12 model (about 480 MB) for CJK or mixed-language archives. Air-gapped installs use --from-file <dir>. Until a model is present, hybrid search runs lexical-only and reports fallback_mode="lexical" in health and status.

Where cass gets in the way: alpha status, model downloads and advisory flags

The README's own badge marks the project as alpha, and the version in Cargo.toml is 0.8.0 while the most recent release listed is v0.7.1 from 2026-08-31. That gap is normal for a project that tags less often than it commits, but it means the source tree and the released binary are not the same thing. If you install from the script you get the release; if you build from main you get something newer and less exercised.

The Rust toolchain is pinned to nightly, according to the README badge and the rust-toolchain.toml entry in the repository root. That is a real constraint for anyone who wants to build from source on a machine with only stable Rust, and it is the reason the Intel macOS path requires --from-source rather than a prebuilt tarball.

Semantic search is the second friction point. It is off until you run cass models install, and the README is clear that nothing is downloaded automatically. On a fresh archive you will get lexical results and a fallback_mode of "lexical" while vectors catch up. If you expected hybrid from the first query, the tool will look worse than it is; if you are on an air-gapped machine, you need --from-file <dir> and a model directory you obtained separately.

Third, the diagnostic surface is deliberately non-destructive. safe_to_gc is advisory, doctor without --fix is read-only, and quarantined artifacts are retained rather than cleaned. That is the correct default for an archive you cannot regenerate, but it means disk usage grows until you act on it yourself. Nothing in the README describes an automatic garbage collection path.

Finally, the licence situation deserves a direct look. The README badge reads MIT+OpenAI/Anthropic Rider, the repository reports NOASSERTION, and Cargo.toml declares license-file = "LICENSE" rather than an SPDX expression. Read the LICENSE file in the repository before you depend on cass in any commercial setting; a badge is not a licence grant.

cass versus a single-harness transcript viewer

The obvious alternative is not another search tool. It is the transcript and resume functionality each agent already ships, plus the related viewers people search for, such as Agent View or Agent Viewer style front ends for one product's sessions. Those tools read one provider's storage format and present it well.

The difference in approach is the index. A single-harness viewer is a reader: it opens the file the agent wrote and renders it. There is no build step, no derived state, and nothing to rebuild when the format changes, because the viewer is updated alongside the agent. cass inverts that. It scans many providers, normalizes them into SQLite, and builds a lexical index on top, which is what makes cross-harness search possible and also what makes the atomic-publish and quarantine machinery necessary in the first place. You are trading a zero-maintenance reader for a maintained index.

That trade is only worth it when you actually have more than one harness in play. With one agent, the viewer wins on every axis: no nightly toolchain, no model download, no backup retention policy to reason about, no quarantine directory to inspect. With four or five agents, the viewer cannot answer the question you are asking, and cass can. The README's provider list is the deciding factor, not the feature list.

Maintenance, upgrades and what the licence actually says

The last push to the repository was on 2026-09-10, and the newest release listed is v0.7.1 from 2026-08-31. The project is not archived. Beyond that, the repository does not describe a support policy, a release cadence commitment or a deprecation process, so upgrade cost has to be inferred from the mechanics.

Those mechanics are mostly reassuring. Because SQLite is the source of truth and every derived asset is rebuildable, a version that changes the index format should be recoverable by rebuilding rather than by migrating. The README states that missing, stale or incompatible lexical assets are treated as derived-state problems cass should rebuild from SQLite instead of asking operators to perform routine manual repair. The retained publish backups under .lexical-publish-backups/ give you one generation of rollback by default, and CASS_LEXICAL_PUBLISH_BACKUP_RETENTION lets you keep more. If you plan to upgrade often, raising that variable before an upgrade is cheaper than discovering you wanted the previous generation after the fact.

The upgrade path itself is the install script with --version <tag>, or the package manager you used originally. Pinning a tag is available on both the shell and PowerShell scripts, which is the practical way to avoid a surprise on a machine where the index matters.

On licensing, the only safe statement is procedural. The README badge says MIT+OpenAI/Anthropic Rider, the repository metadata says NOASSERTION, and the package manifest points at a LICENSE file. Those three sources do not agree in form. Read the file. This is not legal advice, and the discrepancy is exactly the kind of thing a legal review exists to resolve.

Editorial conclusion

Adopt cass if you run several coding agents and have lost the ability to find a past session, and if you are comfortable with a project whose own README labels it alpha and whose semantic search is opt-in and opportunistic. Skip it if you use exactly one agent, since that agent's own resume and transcript commands cover the same ground with no indexing step. Before trusting it, run cass selftest --json on the installed binary and cass diag --json --quarantine to see what it has already quarantined, and check the LICENSE file itself rather than the README badge, because Cargo.toml declares license-file = "LICENSE" and the repository reports NOASSERTION.

Frequently asked questions

Official sources

1. Dicklesworthstone/coding_agent_session_search on GitHub
2. Issues
3. README
4. Releases