Docs / Documentation
glep
Indexed grep and glob for AI coding agents
On this page
glep is a command-line code search tool built for AI coding agents. It replaces two agent tools, Grep (search file contents) and Glob (list files by name), with versions backed by a persistent index.
ripgrep pays the full scan cost on every query. glep pays it once. A trigram index in .glep/ narrows each search to the files that can match, and ripgrep’s own search crates run over just those files. Text output is byte-compatible with ripgrep’s. In continuous integration (CI), a differential harness of about 400 cases runs real ripgrep and glep side by side and compares the bytes, on both the single-thread and the worker-pool search paths.
There is no daemon and no file watcher: one binary and one directory of index files. The only background process is the first index build of a large tree, which runs once and exits.
Versions. These pages describe glep 2.0.0, released on 2026-10-26. It follows 0.3.1 directly. If you are upgrading from 0.3.1, read Upgrading from 0.3.1.
First principles
A coding agent searches the same tree many times in one session. Three facts follow from that:
- Most of a ripgrep query’s cost is reading files that cannot match. A tool that remembers which files contain which 3-byte sequences can skip them. That memory is the trigram index.
- A stored index goes stale the moment a file changes, and an agent edits files between searches. So every query first checks what changed and updates the index before it answers.
- An agent cannot tell a wrong answer from a right one. When the index cannot rule a file out safely, glep searches it instead of guessing. The worst case is ripgrep’s speed, never a missed match.
The rest of the design, and its costs, follow from these three points. How it works walks through them.
Who it is for
Coding agents call Grep and Glob dozens of times per session. On large repositories each call can cost seconds. glep is for that pattern: the same tree searched again and again. The repository ships a Claude Code skill, plus hooks for Claude Code and Cursor that route the built-in Grep and Glob calls through glep.
A minimal example
pip install glep
cd your-project
glep index # one-time build, lazy on first query anyway
glep 'fn parse_intent' src/ # content search (Grep replacement)
glep --files '**/*.py' # file listing (Glob replacement)
How it works, in brief
- A file-level trigram inverted index (the Russ Cox and csearch model) lives in
.glep/, memory-mapped. On the Linux kernel tree it measured about 10% of the corpus size. - Every query self-heals: a parallel freshness sweep compares each file’s modification time (mtime) and size with the index and reindexes only what changed. See Indexing and freshness.
- The regular expression becomes a trigram plan. Intersecting the plan’s posting lists gives a small set of candidate files, and ripgrep’s searcher runs over just those.
- Patterns the index cannot narrow (shorter than three bytes,
.*, anything under-v, and a few more) search every file in parallel. The answer is the same; only the speed changes.
glep is built on ripgrep’s crates (ignore, grep-searcher, grep-regex, grep-printer, regex-syntax), so ignore-file handling, regex matching and output printing are inherited rather than reimplemented.
When to use it
glep wins when the same tree is searched repeatedly.
Use glep for:
- Agent sessions firing dozens of searches over one repository. The bundled hooks reroute Grep and Glob.
- Monorepos where ripgrep takes 100 ms or more per query. On the Linux kernel tree, narrowed queries measured 20 to 234 ms. See Benchmarks.
- Repeated file listings with
glep --files. - Read-heavy bursts with
--ttl 5, which skips the freshness sweep inside the window. - Correctness-critical work: the index self-heals, and unnarrowable patterns fall back to a full scan.
Stick with rg or fd for:
- One-off searches in a tree you will never search again.
- Small repositories where rg already answers in under about 50 ms.
- Ephemeral CI runners or throwaway containers where the index does not persist between runs.
- ripgrep features glep lacks: searching standard input, and
-zfor compressed formats other than gzip. - Corpora dominated by binaries or files over the 1 MB index cap. Those files skip the index and are scanned live anyway.
What it does not do
- No machine-wide or multi-repository index. One index covers one tree.
- No standard input search. A search with no path argument always searches the tree.
-zdecompresses gzip only.- No daemon and no watcher. Freshness comes from the sweep each query runs.
--no-ignore,-L,--one-file-systemand the other flags that change which files exist never use the index. They cost the same as the matching ripgrep run, every time. See Searching file contents.