ripsem

ripsem

Where is the code that does this?

Get started · 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. A search for a name lands on its declaration, with its own lines and label.
• 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.

Get started

1. Install ripsem:

npm (any platform): bash npm install -g ripsem

Cargo: bash cargo install --locked ripsem

macOS and Linux, without npm or Rust: bash curl -fsSL https://raw.githubusercontent.com/Sadykhzadeh/ripsem/master/install.sh | sh

Windows, without npm or Rust: powershell irm https://raw.githubusercontent.com/Sadykhzadeh/ripsem/master/install.ps1 | iex

1. In your repository, ask it something:

bash ripsem search "strip the auth header when redirecting to another host"

1. Hand the same search to your coding agent with ripsem install claude-code or ripsem install cursor (see below).

The first search in a git repository, or in a directory where ripsem init has run, builds the index: it downloads the model (~133 MB) once and embeds the repository. Every search after that first embeds whatever changed since, so results never point at code that has moved. On Windows the first index runs on the GPU through DirectML when there is one.

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

npm and the install scripts put the prebuilt binary from the latest release on your PATH, after checking it against the release's SHA256SUMS. The scripts install to ~/.local/bin and %LOCALAPPDATA%\Programs\ripsem; RIPSEM_INSTALL_DIR overrides that. The release archives can also be unpacked by hand; on Windows, keep DirectML.dll next to ripsem.exe.

The embedding runtime in the x86-64 builds needs a CPU with AVX2 (Intel Haswell, AMD Excavator or newer). The binaries are built with the embedding runtime and tree-sitter; the model itself downloads on first use.

cargo install builds from source, with Rust 1.92 or newer. The build downloads a prebuilt ONNX Runtime, and 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).

Tagged releases are the stable versions, and npm, Cargo and the install scripts all install the latest one. master carries the changes for the next release, listed under Unreleased in CHANGELOG.md.

To build the latest release from a checkout:

git clone https://github.com/Sadykhzadeh/ripsem

cd ripsem git checkout "$(git describe --tags --abbrev=0)" cargo install --locked --path .

Leaving out the git checkout builds master.

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?" # updates the index first 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 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. The first three hits carry their code, up to 40 lines, so the answer can be read without opening the file. 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 runs from 0 to 1: how far the hit's meaning rises above unrelated text in this repository, or the share of the query's terms found literally, whichever is higher. It never rises down the list, so a threshold keeps the top of the ranking. Each index measures its own noise floor by matching queries about anything but code against it, so the scale follows the repository and the model.

The words of a query need no quotes: ripsem search where is auth set up asks the same as ripsem search "where is auth set up".

• -k sets the number of results (default 10).
• --json prints the hits as a JSON array. Each has path, start_line, end_line, score, kind and symbol (such as fn and Session::refresh, both null for a hit outside any declaration) and snippet. With --count-by-file each entry is a path and its count.
• --in limits results to a subdirectory. A relative path starts from the current directory, as in the shell: in src, --in auth means src/auth and --in . means src. An absolute path into the repository works too.
• --context sets how many snippet lines print per hit (3 in a terminal, the whole snippet when the output goes to another program; 0 prints just the locations).
• --min-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

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.

The server sends the same note as its MCP instructions. Claude Code loads the descriptions of MCP tools only when the model looks a tool up, so the model learns that search exists, and when to use it, from the instructions and the note in CLAUDE.md.

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, at most

1. and a min_score. An argument outside the schema comes back as a tool

error that names what is exp