sgrep

Local semantic and hybrid search for codebases and coding-agent history.

Find implementation by intent, then recover the decisions and fixes that led to it across Claude Code, Codex, Cursor, OpenCode, and Pi sessions.

Documentation · Getting started · CLI reference · Agent skill

Why sgrep?

• Search code by meaning instead of guessing identifiers.
• Search prior agent sessions without reopening transcripts one by one.
• Keep source, conversations, models, and indexes on your machine.
• Give coding agents compact file-and-line results instead of large context dumps.

sgrep "where do we validate authentication tokens"
sgrep conv "why did we change the authentication cache key"

Install

brew tap XiaoConstantine/tap
brew install sgrep

# Download the local embedding model and verify llama.cpp.
sgrep setup

See the installation guide for curl, Go, source builds, and sqlite-vec.

Search a Codebase

cd your-repository
sgrep index .

sgrep "database connection error handling"              # balanced, the default
sgrep --profile fast "request routing"                   # lowest latency
sgrep --profile quality "JWT validation middleware"     # optional ColBERT reranking

Profile	Pipeline	Use it for
fast	Semantic	Quick exploration
balanced	Semantic + BM25	Recommended everyday profile; default
quality	Semantic + BM25 + ColBERT	Optional reranking experiments

Code-search guide →

Search Agent Conversations

sgrep conv index

sgrep conv "embedding server ownership bug"
sgrep conv "session compaction" --agent codex --since 7d
sgrep conv resume <session_id>

Conversation search supports Claude Code, Codex CLI, Cursor, OpenCode, and Pi, with semantic, hybrid, and exact retrieval.

Conversation-search guide →

Built for Coding Agents

sgrep complements structural and exact search:

Tool	Finds	Example
sgrep	Intent	sgrep "authentication logic"
ast-grep	Structure	sg -p '$fn($args)'
ripgrep	Exact text	rg "JWT_SECRET"

Install the shared agent skill:

npx skills add XiaoConstantine/sgrep --skill sgrep -g

Claude Code users can also install automatic project indexing and watch hooks:

sgrep install-claude-code

Agent-integration guide →

Architecture

The managed local llama.cpp service is shared, while code and conversation indexes retain separate retrieval controls. The editable diagram source is at docs/static/architecture.tldr.

Architecture details →

Final Pooled Local Benchmark

In the final controlled local-only comparison, sgrep balanced is the strongest overall local quality-latency tradeoff and the strongest normalized implementation-code retriever by point estimate. It is not universally best, and the bootstrap confidence intervals overlap competing tools.

Evaluation track	Point-estimate result
Normalized implementation code	sgrep balanced: MRR 0.792, NDCG@10 0.589, R@10 0.413 at 54.4ms median
Normalized all files	osgrep wins MRR (0.867); sgrep balanced/quality win NDCG@10 and R@10 (0.607 / 0.340)
Native product output	osgrep wins MRR (0.858) and ChunkHound wins R@10 (0.236); sgrep balanced's small NDCG@10 lead is pool-sensitive

The benchmark used 20 queries, model-judged pooled qrels, sgrep source 19ebec1, and the pinned dspy-go corpus at 87cb50f. Query-bootstrap 95% confidence intervals overlap, so these are point-estimate verdicts rather than significance claims. balanced is recommended over quality: it was faster and matched or beat it on the final normalized metrics. Cloud-backed mgrep is kept in a separate, quota-interrupted exploratory track and is not part of the local comparison.

See the benchmark methodology and full tables.

Documentation

Guide	Covers
Getting started	Installation, setup, first searches
Code search	Profiles, output, watch mode, reranking
Conversation search	Sources, filters, view, export, resume
CLI reference	Commands and flags
Configuration	Environment and server modes
Storage	Index files and vector backends
Library API	Embedding sgrep in Go

Development

go build -o sgrep ./cmd/sgrep
go test ./...
golangci-lint run ./...

License

Apache-2.0