ripsem

Where is the code that does this?

Install · Usage · Coding agents · How it works · Troubleshooting

ripsem is local, offline code search for people and for coding agents. Ask with an identifier, an error message or a plain description of the behaviour, and get back the functions and types that answer it, ranked, with their names and line ranges.

• Every shape of question in one query. BM25 over code-aware tokens and vector similarity from a local embedding model, merged into one ranking. A chunk holding every term of an identifier or an error message comes first.
• Answers are declarations. A hit is a whole function or type, named after it, in 17 languages, so a definition reads apart from a call site.
• Made for coding agents. ripsem install claude-code or ripsem install cursor adds an MCP server that keeps its index current while the agent edits, and tells the agent when to use it.
• Offline. No account, no API key, no service. The model downloads once and runs on your CPU, and the index is one file inside your repository.

Quick start

cd your-repo
ripsem index
ripsem search "strip the auth header when redirecting to another host"

The first index downloads the model (~133 MB) and embeds the repository; later runs re-embed only files that changed. ripsem install claude-code hands the same search to a coding agent (see below).

Why not grep?

grep answers "where does this string occur". That is the right question when you know the string. ripsem is for when you know what the code does but not what it is called: a description finds the function, and an identifier or an error message still finds its exact match, because the lexical arm sees it literally. Each hit is a whole function or type with its name, not a matching line, so a reader or an agent can tell a definition from a call site without opening the file.

Install

Every release has a prebuilt binary for each platform below, built with the embedding runtime and tree-sitter (the model itself downloads on first use), and a SHA256SUMS file to check the archives against. Unpack one and put ripsem on your PATH; on Windows, keep DirectML.dll next to ripsem.exe.

archive	runs on
x86_64-unknown-linux-gnu	glibc 2.35, libstdc++ 12 and OpenSSL 3 or newer: Ubuntu 22.04, Debian 12 and later
aarch64-apple-darwin	macOS 13.4 or newer on Apple silicon
x86_64-pc-windows-msvc	Windows 10 or newer with the Microsoft Visual C++ Redistributable

The embedding runtime in the x86-64 builds needs a CPU with AVX2 (Intel Haswell, AMD Excavator or newer).

The same builds come from npm, as ripsem for every platform above:

npm install -g ripsem             # or run it without installing: npx ripsem

To build from source instead, with Rust 1.90 or newer:

cargo install --locked ripsem

The build downloads a prebuilt ONNX Runtime. It needs a C and C++ compiler, plus pkg-config and the OpenSSL headers on Linux (build-essential pkg-config libssl-dev on Debian and Ubuntu).

To build from a checkout:

git clone https://github.com/Sadykhzadeh/ripsem
cd ripsem
cargo install --locked --path .

The fastembed feature, on by default, pulls in the local embedding runtime. Built with --no-default-features, ripsem runs on a lightweight hashing backend that matches words instead of meaning, which is what the test suite uses.

The treesitter feature, also on by default, chunks code on function and type boundaries instead of fixed line windows, and names each chunk after the declaration it belongs to. Results look like src/auth/session.rs:40-72 fn Session::refresh, so a caller can tell a definition from a call site without opening the file. A function too large for one chunk passes its name to every piece. It covers Rust, Python, JavaScript, TypeScript, Go, Java, C, C++, C#, Ruby, PHP, Scala, Kotlin, Bash, HTML, CSS and JSON; other files are cut into line windows.

The hnsw feature adds an approximate-nearest-neighbour graph for indexes above 500 000 chunks. It changes only how the vector arm gathers candidates; the lexical arm and the merge work the same at any size.

Shell completions

ripsem completions bash > ~/.local/share/bash-completion/completions/ripsem
ripsem completions zsh > ~/.zfunc/_ripsem
ripsem completions fish > ~/.config/fish/completions/ripsem.fish
ripsem completions powershell >> $PROFILE

Usage

ripsem init                       # write .ripsem/config.toml
ripsem index                      # build the index (incremental on re-runs)
ripsem search "where is auth set up?"
ripsem status                     # index size, counts, model, drift from the tree
ripsem status --json              # the same as JSON (schema ripsem/status/v1)
ripsem watch                      # keep the index in sync as files change

Like git, every command except init works from any subdirectory: it uses the nearest parent that holds a .ripsem directory. --path <dir> overrides that.

The index stays out of git: .ripsem/.gitignore lists it, so git status shows only config.toml (which can be committed) and that .gitignore. ripsem writes the file when it is missing and never changes an existing one.

status also reports how far the index has drifted from the files. Hits carry the line range their file had when it was indexed, so tree: out of date: 3 changed, 1 new tells you when a result may no longer point at the right lines. Drift is measured with the same content hash the incremental index uses, so it counts exactly what a rebuild would touch. The JSON carries it as index.drift (added/modified/removed).

Results print as path:start-end with the declaration's name and a snippet, in merged-ranking order. Records that cover the same lines (a declaration and the documentation above it, or adjacent windows) are returned once, so -k 5 means five distinct places. The number shown is confidence in 0-1: semantic similarity, or the share of the query's terms found literally, whichever is higher.

• -k <N> sets the number of results (default 10).
• --json prints machine-readable output.
• --in <subdir> limits results to a subdirectory (./src/auth and an absolute path into the repository mean the same).
• --context <N> sets how many snippet lines print per hit (default 3; 0 prints just the locations).
• --min-score <SCORE> keeps only strong matches, in both human and JSON output.
• --count-by-file prints hit counts per file instead of the hits.

Models

ripsem model list                 # show available models
ripsem model set bge-base-en-v1.5
ripsem index                      # rebuilds the index for the new model

Model	Dims	Disk	Notes
bge-small-en-v1.5	384	~133 MB	default
all-MiniLM-L6-v2	384	~90 MB	smallest and fastest to embed
bge-base-en-v1.5	768	~436 MB	larger English model
multilingual-e5-small	384	~470 MB	queries and comments in other languages
nomic-embed-text-v1.5	768	~550 MB	larger English model, the most memory to index

The model downloads once on first use, then everything is offline.

Use with coding agents

ripsem install claude-code        # .mcp.json and a note in CLAUDE.md
ripsem install cursor             # .cursor/mcp.json and a rule in .cursor/rules

install registers the server, writes .ripsem/config.toml, and adds a short note that tells the agent to reach for search before grepping. Restart the agent in the directory and it can call search directly.

ripsem mcp speaks MCP over stdio and exposes a single search tool: a query, and optionally a path to stay inside, a limit (default 5) and a min_score. In a directory with a .ripsem directory the server keeps the index current by itself: it builds the index on its first start and re-embeds every file the agent changes. Running ripsem index once beforehand has the index ready before the first search.

Any other MCP client takes the same entry in its own config:

{
  "mcpServers": {
    "ripsem": { "command": "ripsem", "args": ["mcp"] }
  }
}

Without ripsem installed, the client can start it through npm with "command": "npx", "args": ["-y", "ripsem", "mcp"].

The server finds the index from the directory it starts in. To point it at a repository elsewhere, add "--path", "/path/to/repo" to args; install cursor writes "--path", "${workspaceFolder}", which Cursor expands to the project.

Configuration

.ripsem/config.toml:

backend = "fastembed"
model = "bge-small-en-v1.5"
chunk_lines = 40
chunk_overlap = 8
max_chunk_lines = 50
max_file_kb = 1024
skip_generated = true
exclude = []

chunk_lines and chunk_overlap size the line windows used for plain-text files and languages without a parser. max_chunk_lines caps a single semantic chunk; larger functions are split. After changing any of the three, the next ripsem index chunks and embeds every file again. Files larger than max_file_kb are skipped. exclude takes gitignore-style globs, on top of .gitignore and an optional .ripsemignore. backend = "hash" matches words instead of meaning; builds without the fastembed feature start with it. A key ripsem does not know is reported as an error.

skip_generated leaves out files that are committed but written by a machine: lock files, go.sum, *.min.js, *.min.css and source maps. .gitignore does not cover them because they are committed on purpose, and a single lock file can outweigh everything written by hand. Set it to false to index them anyway.

How it works

flowchart LR
    subgraph index ["ripsem index"]
        files["files"] --> chunks["chunks: functions, types,<br/>doc comments"]
        chunks --> vectors["embedding vectors"]
        chunks --> terms["code-aware terms"]
    end
    subgraph search ["ripsem search, MCP search"]
        query["query"] --> dense["vector similarity"]
        query --> bm25["BM25"]
        dense --> fusion["rank fusion"]
        bm25 --> fusion
        fusion --> places["ranked places:<br/>path, lines, declaration"]
    end
    vectors -.-> dense
    terms -.-> bm25

1. Walk. The tree is read the way git sees it: .gitignore, the global gitignore and .ripsemignore apply, and binary files, files above max_file_kb and machine-written files are left out.
2. Chunk. tree-sitter cuts each file at function and type boundaries and names every chunk after its declaration. A doc comment or docstring becomes a second record for the same declaration, because an author describes code in words the code itself rarely uses.
3. Embed and tokenise. Each chunk gets a vector from the local model, stored as int8, and a set of terms in which identifiers are kept whole and also split at snake_case and camelCase boundaries.
4. Search. The query runs through both arms and their rankings are merged by reciprocal rank fusion. A chunk holding every informative term of the query comes first, which is what makes identifiers and error messages reliable; below that, code ranks above prose that describes it.
5. Keep up. The index is one file, .ripsem/index.bin. A re-run embeds only files whose content changed; a new model or new chunk settings rebuild it. ripsem watch keeps it current as files change, and the MCP server picks up a rebuilt index without a restart.

Troubleshooting

A file never shows up in results. ripsem index --dry-run lists every file the index takes in. A file is left out when .gitignore, .ripsemignore or exclude matches it, when it is binary or larger than max_file_kb, or when skip_generated treats it as machine-written.

A result points at the wrong lines. The file changed after it was indexed. ripsem status shows how far the index has drifted; ripsem index brings it up to date, and ripsem watch or a running MCP server keeps it there.

Search says the index was built with another model. The config names a different model or backend than the index. ripsem index rebuilds it for the config.

The agent does not call search. The server starts with the agent, so restart the agent in the repository after install. In Claude Code, /mcp lists the servers it has connected to.

The first index takes a while. It downloads the model once and embeds every file. Every later run embeds only the files that changed. The model is cached in ~/.cache/ripsem on Linux, ~/Library/Caches/ripsem on macOS and %LOCALAPPDATA%\ripsem\cache on Windows.

ripsem.exe fails to start on Windows. A missing VCRUNTIME140.dll or MSVCP140.dll means the Microsoft Visual C++ Redistributable is not installed: winget install Microsoft.VCRedist.2015+.x64 adds it. A missing DirectML.dll means it was not kept next to ripsem.exe when the archive was unpacked.

Quality

Ranking is held to a benchmark of labelled questions over four real projects in four languages (Rust, Python, Go and TypeScript), each pinned at a release tag. The questions come in the four shapes people actually search with: a description in their own words, an identifier, a message seen in output, and a name remembered wrong. The merged ranking has to beat either retriever alone, put the answer in the top five for at least 86% of the questions, and cost less to read up to the answer than the file the answer is in.

cargo test --release \
  --test retrieval_quality -- --ignored --nocapture fusion_beats_either_retriever_alone

The first run clones the four projects into target/corpora and downloads the model. CONTRIBUTING.md describes how a change to ranking is measured.

License

Apache-2.0