Ivygrep README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Ivygrep listing page.
Turn coding tasks into bounded, branch-aware context.
Search, indexing, and context generation run locally. Optional model profiles download pinned assets on first use.
Website · Architecture · Benchmarks · Contributing · Discussions
Search and build context
Abridged output:
Search answers where. Context answers what an agent needs to change safely.
The context command combines task anchors with commits since the branch point, staged and dirty files,
issue or trace paths, and indexed relationships. It returns one bounded Markdown pack with path, lines,
role, reason, and retrieval signals. --since requires a Git worktree; omit it for non-Git directories.
Install
Installers select a compatible archive, verify its SHA-256 checksum, install ig, and report the selected backend. Apple Silicon uses Metal. NVIDIA Linux hosts use the Linux x86_64 CUDA build when CUDA 13 and compute capability 8.0 or newer are available. Other systems use portable local inference. Run ig hardware to see detected hardware, compatibility limits, and the matching reinstall command.
Build from source on macOS or Linux:
Search
The first query indexes the current repository. The daemon then watches for changes and updates the index incrementally.
Useful controls include -n for result files, -C for context lines, --type
for language, --include/--exclude path globs, --lexical-only, --hash, and --json. --hash
uses lightweight local embeddings for faster startup and no model download,
with lower semantic quality. Run ig --help for full reference.
On macOS laptops, background neural enhancement pauses on battery power (ig --status
shows Paused: Battery Power); set IVYGREP_ENHANCE_ON_BATTERY=1 to keep it running.
The lightweight hash tier keeps computing on battery so semantic results stay available.
Search notes and memories
Index notes once. Watcher keeps them current, and queries use local semantic + lexical search by default:
Public MemoryQuest results: 74.9% recall@20 at 87.63 ms warm p95. Benchmark measures retrieval only; answer accuracy is outside scope.
Connect coding agents
Codex and Claude Code packages install MCP configuration plus focused task-context skill:
Automatic setup detects the client, preserves existing configuration, writes the absolute ig path, verifies the MCP handshake, and runs a search:
Restart an open client after installation. Manual MCP setup is also available:
Cursor .cursor/mcp.json:
OpenCode opencode.json:
Agents call ig_search for discovery. Set output=context_pack and budget_tokens=8000 when the task needs implementation context. Pass the absolute path to the active repository or worktree. Worktrees reuse the base index and store only changed chunks and tombstones.
Context packs can include definitions, callers, references, dependencies, dependents, tests, configuration, and docs.
Setup guides: Codex, Claude Code, Cursor, Gemini CLI, OpenCode, and MCP.
Recommended agent instruction:
How it works
- A Git-aware walker finds changed or indexable files.
- Tree-sitter and bounded text fallbacks produce structural chunks.
- SQLite stores metadata and relationships; Tantivy stores lexical postings; USearch stores hash and optional model vectors.
- Query routing runs bounded exact, lexical, symbol, hash, and optional neural passes before fusion.
- Context expands primary hits through code relationships and recent changes, then trims rendered evidence to requested token budget.
Fresh indexing publishes lexical results before vector enhancement. Worktrees reuse base index and store only divergent chunks and tombstones. Partial workspace failures return warnings with valid hits; complete failure errors.
ivygrep supports 45 language and file types. Twenty-four use Tree-sitter AST chunking: Rust, Python, Go, JavaScript, TypeScript, Java, C/C++, C#, Kotlin, Scala, PHP, Ruby, Swift, Elixir, Zig, Bash, Haskell, OCaml, Lua, Dart, Objective-C, Perl, and Starlark.
Read architecture for storage, commit order, retrieval, worktrees, protocols, security boundaries, and module ownership.
System performance
On the deterministic synthetic one-million-chunk CC0 corpus, v1.2.7 median hash-only warm CLI p95 is 6.19 ms, controlled indexing reaches 150,576 chunks/s, and the final index is 0.42 GiB across three sequential trials. This is a scale and footprint measurement, not semantic quality or agent-task performance. Hardware, repository shape, index state, and load affect absolute results.
Current-release evidence · Million-chunk methodology and historical paired study · Full benchmark dashboard
Local and private
Runtime source, queries, embeddings, results, and indexes stay local. Neural
profiles download pinned model assets on first use unless cache is already
populated. Use --hash, ./build.sh --hash-only, or
cargo build --locked --no-default-features to avoid model downloads.
ig --web binds to loopback by default. A non-loopback listener prints an authenticated URL but still uses plain HTTP. Use a trusted network, Tailscale, or an encrypted tunnel, and never expose the listener directly to the internet. File contents, including non-ignored dotfiles, can appear in the local index and snippets.
Report vulnerabilities through a private security advisory. Release archives include checksums, SBOMs, and provenance.
Contribute
Start with a good first issue, read CONTRIBUTING.md and architecture, or discuss an idea in Discussions.
MIT licensed. Maintained by Bruno Volpato.