glep 0.3.1

Indexed grep + glob for AI coding agents.

Documentation: https://velofy.co/glep/

ripgrep pays the full scan cost on every query. glep pays it once: a persistent, self-healing trigram index answers warm queries in 21 to 298 ms on a Linux-kernel-sized tree where ripgrep takes 1.4 s, with text output byte-compatible with ripgrep's, enforced by a 24-case differential harness in CI. No daemon.

Install

pip install glep          # binary wheel, no Rust toolchain needed
# or
cargo install glep

pipx install glep and uv tool install glep also work. crates.io currently has 0.2.3; PyPI has 0.3.0. See Installation for platforms and other routes.

Example

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'          # glob listing (Glob replacement)

Features

• Trigram index in .glep/, memory-mapped, about 10% of corpus size on the kernel tree.
• Self-healing: every query runs a parallel mtime sweep and reindexes only what changed. No watcher, no background process.
• Sound fallback: patterns the index cannot narrow fall back to a full parallel scan. Never a wrong answer; worst case is ripgrep speed.
• ripgrep-compatible: built on ripgrep's crates (ignore, grep-searcher, regex-syntax). Text output is byte-compatible with rg; --json emits rg's event stream including the closing summary event.
• Familiar flags: -i -F -l -c -U -e -g -t -C -A -B --json --hidden --no-ignore.
• Agent integrations: a Claude Code skill and PreToolUse hook (claude/install.sh) and a Cursor hook (cursor/install.sh) that route built-in Grep/Glob calls through glep.

Interface

glep 'fn parse_intent' src/     # content search (Grep replacement)
glep --files '**/*.py'          # glob listing (Glob replacement)
glep --json 'pattern'           # machine-readable output (includes rg's summary event)
glep -c 'pattern'               # per-file match counts (rg -c)
glep -l -i -F -U ...            # files-with-matches, case-insensitive, fixed, multiline
glep -A 2 -B 1 'pattern'        # context, or -C n for both sides
glep -g '*.rs' -t rust ...      # glob and type filters
glep --hidden 'TODO'            # include dotfiles (.git is always excluded)
glep --no-ignore ...            # search ignored files too (live scan, index untouched)
glep --ttl 5 ...                # skip the freshness sweep within a read burst
glep --max-filesize 2000000 ... # raise the 1MB index cap
glep index                      # explicit (re)build; lazy on first query
glep status                     # index stats

--no-ignore always pays a full scan: it bypasses the index entirely, so gitignored trees never enter it. It costs the same as rg --no-ignore, every time.

With an explicit path argument, bytes_printed in the JSON summary can differ from rg's (rg prints ./-prefixed paths; glep prints them bare).

Other known differences from rg: files with a NUL byte in the first 8 KB (including UTF-16 text) are treated as binary and never searched, and .gitignore rules apply even outside a git repository (like rg --no-require-git). The index lives in .glep/ in the directory you run glep from, so run it from the project root.

When to use it

Use glep for:

• Agent sessions firing dozens of searches over one repo (the bundled hooks reroute Grep/Glob).
• Monorepos where rg takes 100 ms or more per query.
• Repeated glob listings: glep --files reads the manifest, no re-walk past the freshness sweep.
• Read-heavy bursts with --ttl 5 to amortize the freshness sweep.
• Correctness-critical work: self-healing index, sound full-scan fallback.

Stick with rg / fd for:

• One-off searches in a tree you will never search again.
• Small repos where rg already answers in under about 50 ms.
• Ephemeral CI runners where the index never persists between runs.
• rg features glep lacks: replacements, PCRE2, compressed files.
• Corpora dominated by binaries or files over the 1 MB cap (live-scanned anyway).

Numbers

Linux kernel 6.12 checkout: 86,605 files, about 1.5 GB. Apple Silicon macOS, hyperfine medians, warm filesystem cache, rg and fd at their default parallelism.

Index build (one-time): 24 s. Index size: 154 MB. Default glep pays the freshness sweep (a stat of every file) on each query; --ttl amortizes it across read bursts. Details: Benchmarks.

Documentation

• Overview
• Installation and Quickstart
• Indexing and freshness
• Searching file contents and Listing files by name
• Claude Code and Cursor integrations
• CLI reference and Output formats
• Changelog

Design spec: docs/superpowers/specs/2026-07-14-glep-design.md.

Contributing

Issues and pull requests are welcome at https://github.com/velofy/glep. CI runs on Linux, macOS, and Windows:

cargo test --all                                  # parity tests need rg on PATH
cargo build
PATH="$PWD/target/debug:$PATH" claude/hooks/test_hook.sh
PATH="$PWD/target/debug:$PATH" cursor/hooks/test_hook.sh

CI also rejects em dash and en dash characters anywhere in the repository.

License

MIT. See LICENSE.