tgrep
Trigram-indexed grep with a client/server architecture for fast regex search
in large codebases.
tgrep is integrated into GitHub Copilot CLI
to power fast grep searches across large repositories.
Quick start
Install tgrep, then start a server:
tgrep serve . # builds the index if needed; runs in the foreground
In another terminal:
tgrep -- "fn main" . # automatically connects to the server
tgrep status . # show indexing and refresh status
Without a server, run tgrep index . to build an on-disk index. Searches use
the server when available, then the local index, or scan the filesystem if no
usable index exists. Indexes are stored in .tgrep/ by default; add this
directory to .gitignore. It is generated build output and must not be committed
or distributed with a repository. Build indexes locally for repositories you
search; index metadata is not a statement of trust or freshness.
Indexed file reads stay beneath the selected root and do not follow descendant
symlinks or Windows reparse points. Invalid stored paths are rejected; indexes
with an unavailable or unrelated recorded root fall back to a filesystem scan.
Explicit file arguments and --no-index --follow retain their normal scan
semantics.
Indexes can lag filesystem changes. The server updates asynchronously;
without a server, rerun tgrep index . after changes. Use --no-index when a
search must read the current files. Queries scan during an initial build until
complete coverage is available.
For coding agents, see AGENTS.md. To install MCP search tools and
startup hooks for Codex or pi, run bash install-agent.sh from this checkout
(Linux/macOS, Python 3.11+). See the
agent integration guide.
Performance
A trigram index narrows each query to files that could match, then verifies
those files with the regex engine in parallel. Patterns without useful
trigrams may still require searching every indexed file.
In the August 24, 2026 benchmark sweep, tgrep was faster than ripgrep in 17 of
18 repo/platform combinations, with speedups from 0.93x to 51.9x. These measure
client/server search latency with the index already built, not indexing time.
Results depend on the query, repository, storage, and match volume. See
BENCHMARKS.md for measurements and methodology.
Shared-worktree benchmark
The shared-worktree baseline compares one ordinary
server/index per worktree with one shared daemon across 1, 4, 16 and 32 synthetic
Git worktrees. It covers LF, clean CRLF, private branch changes and bounded churn,
with scan-checked results, fresh/restart startup, query percentiles, reconciliation
counters, process resources and retained storage. It includes a small Windows/Linux
smoke command and distinguishes logical sharing from OS page-cache and RSS effects.
The measured baseline saves LF memory/storage but has higher startup/query latency;
clean CRLF can cost more memory/storage too. Shared mode remains opt-in.
Usage
Build the index
tgrep index . # index current directory
tgrep index /path/to/repo # index a specific repo
tgrep index . --index-path /tmp/idx # custom index location
tgrep index . --exclude vendor --exclude third_party # skip directories
Each build reports elapsed time and, where available, peak memory:
Index built successfully at /tmp/idx
Indexed in 22.6s using external strategy (peak memory 160.1 MiB)
Windows reports peak private committed bytes; Linux samples anonymous resident
memory. Both exclude file-backed mappings and report the working set separately
when it is substantially larger. macOS reports resident memory instead.
Repositories without a .git directory
Like ripgrep, tgrep applies .gitignore only inside a Git repository. It warns
when a root .gitignore is present but not applied. Use --no-require-git on
indexing, serving, and searching to apply those rules outside Git:
tgrep index . --no-require-git
tgrep serve . --no-require-git
tgrep --no-require-git -- "pattern" .
Case-insensitive repositories
When Git's core.ignorecase is enabled, tgrep applies an additional
case-insensitive exclusion pass for the repository's root .gitignore and
.git/info/exclude. Git-tracked paths are exempt from this additional pass,
but not from ordinary traversal, binary, or size filtering.
Nested .gitignore files and global ignore rules do not get this additional
pass. --no-ignore disables it along with the normal ignore rules.
Keep index and serve flags in step
Use the same --no-require-git, --no-ignore, --max-filesize (or
--no-max-filesize), and --exclude settings for index and serve.
Startup reconciliation removes indexed files excluded by the server's current
settings. For example, serving an uncapped index with --max-filesize 8M
removes files larger than 8 MiB from that index.
Pass the same size policy, --no-require-git, and any custom --index-path
to searches too. --exclude is only available on index and serve;
--no-ignore on a search forces a filesystem scan.
tgrep index . --max-filesize 8M
tgrep serve . --max-filesize 8M
tgrep --max-filesize 8M -- "pattern" .
Memory use on very large repos
tgrep index defaults to an external merge sort with a 64 MiB posting buffer.
When the buffer fills, sorted segments spill to disk and are merged into the
index. This bounds posting-buffer memory, not total process memory: file
tables, worker buffers, and decoded content also consume memory.
tgrep index . # external, 64 MiB posting buffer
tgrep index . --index-buffer 16 # smaller buffer, lower peak
tgrep index . --index-strategy=memory # sort entirely in RAM
This is the beginning of the README. Read the rest at the original. Read the full README ↗
