ssgrep

About

Your coding-agent transcripts contain problems you already solved, but ordinary text search is poor at finding a solution when you remember the idea rather than the exact words. ssgrep turns the prompt/response episodes in those transcripts into a local search index.

• One global index — Discovers transcripts from every supported coding agent on the machine and reconciles them into a single local LanceDB database
• Semantic search — Late-interaction ColBERT embeddings with native MaxSim scoring; searches work on paraphrases, not just exact words
• Fully local and offline — After a one-time model download, indexing, search, and the MCP server run without network access
• Agent-ready — ssgrep init installs an ssgrep skill into each agent harness, and an MCP server exposes search plus an explicit save_note write tool to any MCP client
• Opt-in savings ledger — Local lookup observations, explainable modeled scenarios, and separately authorized organization export; never a productivity ranking. Start with docs/savings.md.

Requires macOS or Linux (Windows is not supported) and Python 3.11+.

CI tests Python 3.13 only; Python 3.11 and 3.12 are not exercised.

ssgrep init
ssgrep search "how did I handle async migration failures"
ssgrep show <ref>

Quick Start

Install

Try it without installing (fetched from PyPI and cached):

uvx ssgrep --version

Install globally with uv (recommended):

uv tool install ssgrep
ssgrep --version

Or with pip:

pip install ssgrep

Upgrade with uv tool upgrade ssgrep; remove with uv tool uninstall ssgrep.

[!NOTE] Indexing/search downloads torch and the ColBERT embedding model once (a few hundred MB in total), then works offline. Local accounting needs no LLM or network; optional organization export requires separate consent.

Use with Your Coding Agent

One command sets everything up — it registers the ssgrep mcp server with every supported client (Claude Code, Cursor, Zed, Codex CLI, opencode, omp), installs an ssgrep skill into each agent harness, and builds the global index:

ssgrep init

Prefer to register only the MCP clients, or skip one?

ssgrep mcp install            # every supported client
ssgrep mcp install cursor zed # a subset

Or register a client manually (per-client snippets in docs/mcp-setup.md):

claude mcp add --scope user ssgrep -- ssgrep mcp

That's all an MCP user has to do. On startup the server discovers every supported coding agent on the machine and builds the global index itself (the first run downloads the ColBERT embedding model from Hugging Face; after that everything is offline). It reconciles new transcripts on every start, so the index stays current without manual commands. Then just ask your agent to search — e.g. "search my sessions for how I fixed the flaky migration test".

The installed ssgrep skill teaches the agent to search before solving, open hits with show, and capture durable lessons with note (see docs/agent-guidance.md).

Use from the Terminal

The CLI searches the same index the MCP server maintains:

ssgrep search "how do I handle async errors"

# Inspect one result using the ref printed by search
ssgrep show <ref>

# Inspect index counts, archive state, and runtime census
ssgrep status

To keep the index fresh when working only from the terminal, run ssgrep index to reconcile new or changed transcripts.

Usage

Run ssgrep --help or ssgrep <command> --help for the installed CLI's authoritative option list.

Command	Purpose
ssgrep init	One-time setup: install agent skills, then index
ssgrep index	Build or update the global index
ssgrep search <QUERY>	Find relevant episodes
ssgrep show <REF>	Inspect one episode's prompt and response
ssgrep status	Inspect index counts and database state
ssgrep note	Add a durable searchable note
ssgrep prune	Permanently delete archived content
ssgrep mcp	Start the MCP stdio server
ssgrep rules	Print the operating rules installed by init

Search is global by default; narrow it with --where predicates:

ssgrep search "retry policy" --where "project = '/absolute/path/to/app'"
ssgrep search "tool failure" --where "is_subagent = true AND content_type = 'response'"

Data-oriented commands accept a global --json flag. A transcript that is no longer discovered stays searchable but is marked source_status = 'absent'; restrict to live sources with --where "source_status = 'available'" and clean up archived content with ssgrep prune.

After the first ssgrep init, run ssgrep index any time to reconcile new or changed transcripts into the global index.

See docs/usage.md for the full command reference, --where predicate fields, exit codes, JSON envelopes, and archive semantics.

Supported Agents

ssgrep ingests sessions from every coding agent it can find on the machine, through one adapter per runtime. Each adapter reads only the runtime's own on-disk transcript data and normalizes it into one shared episode schema.

Runtime	Transcript source	Default location
Claude Code	native record-pair JSONL	~/.claude/projects
OpenCode	local SQLite store	~/.local/share/opencode/opencode.db
Codex	rollout session JSONL	~/.codex/sessions
Pi	session JSONL	~/.pi/agent/sessions
omp	session JSONL (Pi format)	~/.omp/agent/sessions
Prime Agent	session JSONL + session-artifacts/	~/.prime/agent/sessions

ssgrep status reports the runtime census (Runtimes: claude=12, opencode=3, ...), and every search can be narrowed with --where "runtime = 'pi'".

ssgrep init installs an idempotent ssgrep skill into each runtime's own global skills directory. The installed rules tell agents to search before solving, read hits with show, and capture durable lessons with note — see docs/agent-guidance.md.

See docs/runtimes.md for per-runtime ingestion details, environment overrides, and model/device configuration.

MCP

ssgrep mcp starts an MCP stdio server with read-only search_sessions, show_session and index_status, plus save_note for explicitly saving local knowledge and optional original-investigation metadata. It builds and refreshes the shared index on startup — see Quick Start for registration.

ssgrep mcp install registers every supported client (Claude Code, Cursor, Zed, Codex CLI, opencode, omp) in one step; manual snippets and full tool details are in docs/mcp-setup.md.

Privacy

1. Transcripts stay local. Indexing and search run on your machine; transcript content is not sent to an LLM or hosted retrieval service.
2. Runtime is offline after the model is cached. The first model download uses Hugging Face; warm loads are cache-first, and update checks and pipeline usage telemetry are disabled by default (override with COCOINDEX_DISABLE_USAGE_TRACKING=0 if you want cocoindex's own telemetry back).
3. Transcript history is read-only. ssgrep never writes to any agent's transcript files; note writes only to ssgrep's own application-data directory.
4. No automatic listener or daemon. CLI commands are local processes and MCP uses stdio. Only an explicit ssgrep savings serve starts an authenticated loopback listener; setup installs no service.

The index contains copies of transcript text in the application-data root (created with mode 0700). Protect and back up that directory accordingly.

Local accounting and remote export default off. ssgrep savings setup previews and enables local measurement only; ssgrep savings collect produces a snapshot, and ssgrep savings reads it (refreshing stale or missing snapshots unless --no-refresh is used). Raw transcripts are not exported. Optional organization metrics and separately permitted pseudonymous ledger logs require explicit consent for each destination and signal. Modeled estimates are not causal ROI or human time saved; current remediation verification is pending. See exporting data for the three output surfaces, savings and privacy controls, export limits and revision-specific evidence.

Docs

• docs/usage.md — full command reference, predicate fields, exit codes, JSON output, archive semantics
• docs/runtimes.md — per-runtime ingestion, environment overrides, model and device configuration
• docs/retrieval.md — chunking, embedding, scoring pipeline, measured benchmark results
• docs/agent-guidance.md — the ssgrep operating rules installed into agent harnesses
• docs/mcp-setup.md — MCP client configuration and tool details
• docs/architecture.md — discovery, reconciliation, schemas, and service-layer details
• docs/savings.md — local opt-in, collection, receipts, pause/purge, and optional service
• docs/exporting-data.md — local JSON report, loopback /metrics and /v1/snapshot, organization OTLP export with sample output
• docs/accounting-methodology.md — observations, scenario estimates, uncertainty and validation limits
• docs/organization-metrics.md — export consent, collector examples, acknowledgment and dashboard semantics
• docs/accounting-benchmarks.md — revision-specific accounting evidence, learnings and pending verification

🚀 Credits

• Multi-vector search was significantly improved by @thememium.

License

MIT License. See LICENSE.