# sgrep

> A local command-line tool that searches code and documents in plain English using static embeddings and BM25, and can rank ripgrep results.

sgrep is an open-source command-line search tool from Context.dev that finds local code and document passages by words and meaning. It runs on the user's machine without an account, hosted index, or model server. The latest listed release is v0.3.0, titled "code and document search".

## What It Is

sgrep is a local semantic search CLI aimed at cases where an agent or developer knows what code should do but not what to search for. You run a natural-language query against a directory, and it returns the file, line range, and source passage for each match. Results are source passages, not generated answers. Options include `-n` for result count and `--json` for JSON output.

## Search Workflow and Ripgrep Piping

In the standard mode, sgrep uses ripgrep to list files, splits them into passages with Chonkie and Tree-sitter, and combines the top 200 lexical matches with the top 200 semantic matches. Scores blend 75% semantic and 25% BM25, and exact case-sensitive identifier matches rank first. Code parsers cover Python, C/C++, Go, Java, Rust, JavaScript/JSX, and TypeScript/TSX; other files use text splitting.

sgrep can also rank only the output of a focused `rg --json` command by reading it with `--stdin`. Saved ripgrep results can be added with `--rg-json`. Piped ranking does not use the index.

## Models and Local Operation

sgrep uses static embeddings from Minish Lab: Potion Code 16M v2 for code and Potion Base 8M for prose. Each passage is represented as a 256-number vector with no transformer pass at search time. Auto mode picks the text model only when all candidates have prose extensions such as .md or .txt; `--model code` or `--model text` overrides this. The first search downloads a model (32-34 MB) and any needed parsers, after which searches can run offline. PDFs and images are not parsed.

## Caching and Setup

Installation requires Rust 1.90 or later and ripgrep, via `cargo install` from the repository, or a macOS Apple Silicon binary from the releases page. A local index stores copies of source passages, capped at 256 MiB and 128 entries by default. Flags such as `--refresh-cache`, `--no-cache`, `--cache-dir`, and `--fresh-assets` control caching and downloads.

## Benchmarks Published by the Project

The README reports that piped sgrep used 21.3% less LLM API spend than ripgrep on a SWE-bench Verified subset, with 70/100 versus 68/100 solved attempts. It also states that CK's semantic mode beats sgrep on its CoSQA test, while sgrep leads on complete-function retrieval in RepoQA. These are the project's own measurements, and they cover code retrieval, not document search.

## Features
- Plain-English semantic search over local code and documents
- Hybrid ranking combining static-embedding semantic scores with BM25
- Exact case-sensitive identifier matches ranked first
- Rank ripgrep results via --stdin or --rg-json
- Syntax-aware chunking for Python, C/C++, Go, Java, Rust, JavaScript/JSX, TypeScript/TSX
- Automatic or explicit code/text model selection
- JSON output with optional score explanations
- Local index cache with configurable limits and offline operation

## Integrations
ripgrep, Tree-sitter, Chonkie, Model2Vec, Hugging Face Hub

## Platforms
MACOS, LINUX, API, CLI

## Pricing
Open Source

## Version
v0.3.0

## Links
- Website: https://github.com/context-dot-dev/sgrep
- Documentation: https://github.com/context-dot-dev/sgrep#readme
- Repository: https://github.com/context-dot-dev/sgrep
- EveryDev.ai: https://www.everydev.ai/tools/sgrep