ivygrep

Search code and notes. Build context for coding tasks.

Files and queries stay on your machine. The default model downloads its pinned assets on first use.

Website · Architecture · Benchmarks · Contributing · Discussions

Search and build context

# Find code by intent

ig "where is refresh token rotated?"

Build context from code and current changes

ig context "fix refresh-token races" --since main --budget 8000

Abridged output:

# ivygrep context

Budget: 7642 / 8000 estimated tokens Coverage: 7 files | 2 primary | 1 definitions | 1 dependencies | 0 dependents | 2 callers | 0 references | 1 tests | 0 config | 0 docs Candidates: 31 retrieved | 14 selected

Evidence

1. src/auth/refresh.rs:118-166 [primary, definition]

Why: task anchor; changed implementation. Signals: lexical, symbol, git change.

Search returns ranked file paths, line numbers, and previews. Context packs add related code and explain why each item was selected.

The context command uses your task, file paths in pasted text, and staged or uncommitted changes. With --since, it resolves the selected ref and finds its Git merge base with HEAD. The pack includes changes committed on the current branch since that base, plus staged, unstaged, and untracked files. The selected ref does not act as the diff base itself. Deleted changes can contribute Git history labeled git_deleted to a context pack. The unreleased deletion fix excludes missing files from current search results. The pack can include definitions, callers, dependencies, tests, configuration, and documentation. It trims the rendered Markdown to the requested estimated token budget. It does not generate an answer or modify files.

Use --since main, --since HEAD~3, or --since '@{upstream}' inside a Git worktree. For a directory without Git, omit --since.

Install

# Homebrew on macOS or Linux

brew install bvolpato/tap/ivygrep

Release installer on macOS or Linux

curl -fsSL https://raw.githubusercontent.com/bvolpato/ivygrep/main/install.sh | sh

# WinGet on Windows

winget install --id BrunoVolpato.ivygrep --exact

Release installer on Windows

irm https://raw.githubusercontent.com/bvolpato/ivygrep/main/install.ps1 | iex

Installers select a compatible archive, verify its SHA-256 checksum, and install ig. The shell installer selects a Metal build on Apple Silicon. It selects CUDA only on Linux x86_64 when an NVIDIA GPU with compute capability 8.0 or newer is visible and the CUDA 13 runtime is available. Other supported hosts use the portable build. Homebrew installs the Metal build on Apple Silicon and portable builds on Intel macOS and Linux. CUDA and Metal accelerate optional transformer profiles; the default model runs on CPU in every build. Run ig hardware to check compatibility and see the matching reinstall command.

Build from source on macOS or Linux:

git clone https://github.com/bvolpato/ivygrep.git && cd ivygrep

./build.sh mkdir -p ~/.local/bin install -m 0755 target/release/ig ~/.local/bin/ig

Search

The first query indexes the current repository. The daemon then watches for changes and updates the index incrementally.

Starting with v1.3.1, search immediately excludes a file that the safe file reader confirms is missing, even before watcher reconciliation. Reconciliation then removes entries owned by that workspace. Permission, unavailable, and symlink failures are not treated as deletion. Earlier releases retain the indexed-text fallback for missing files.

Linked Git worktrees share a base index. An overlay tombstone hides a base-backed file deleted on that branch without changing what other worktrees can search. Deleting a file added only in the worktree removes its overlay entries and does not need a base tombstone.

ig "where is authentication handled?"       # hybrid semantic + lexical

ig --literal "handleAuth" # exact indexed lookup ig --symbol calculate_tax # definitions ig --refs calculate_tax # references and calls ig --callers calculate_tax # caller chunks ig "database migrations" src/api/ # path scope ig --all "retry policy" # all indexed projects ig --interactive "auth flow" # terminal UI ig --web "auth flow" . # local Web UI

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.

Literal search ranks files by matching lines. A bounded search shows up to three previews per file and reports omitted matches. Use --no-limit to return every match, or --file-name-only to return paths without building previews.

Standalone uppercase AND, OR, and NOT are Boolean operators. For example, ig "settings NOT render" excludes results that contain render. Short malformed expressions, such as a trailing OR, return an error.

If an invalid Boolean query spans multiple lines or has at least 13 words, ivygrep searches it as plain text. The results include a warning. The CLI writes it to stderr. MCP and the Web UI return it in warnings. Valid Boolean expressions keep their Boolean meaning, including in long prompts. To search operator words as text, use lowercase letters or wrap the words in backticks or quotes.

Multi-line queries that read as pasted source rank the code that contains the snippet above one-line definition signatures that share a few of its identifiers. Multi-paragraph prompts, pasted issue text, and questions with a blank line rank as prose, with signature matches scored like body text. For pasted error output, such as a traceback, a Caused by: chain, or a panicked at line, lexical, path, hash-vector, and reranking signals ignore runtime values such as paths outside the workspace, ids, and timestamps, and the static message text is matched against the code that raises it. Neural query vectors still embed the original text.

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. However many workspaces change at once, at most two hash and two neural enhancement workers run at a time (IVYGREP_ENHANCE_MAX_WORKERS); the rest wait in the daemon, and the workspace searched or edited last goes first.

Search notes and memories

Index notes once. Watcher keeps them current, and queries use local semantic + lexical search by default:

ig --add ~/notes --wait-for-enhancement

ig -n 20 "what did we decide about cache invalidation?" ~/notes

Public MemoryQuest results (v1.2.7): 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:

codex plugin marketplace add bvolpato/ivygrep

codex plugin add ivygrep@ivygrep

claude plugin marketplace add bvolpato/ivygrep claude plugin install ivygrep@ivygrep

Automatic setup detects the client, preserves existing configuration, writes the absolute ig path, verifies the MCP handshake, and runs a search:

ig agent install claude

ig agent install codex ig agent install cursor ig agent doctor

Restart an open client after installation. Manual MCP setup is also available:

claude mcp add -s user ig -- ig --mcp

codex mcp add ig -- ig --mcp gemini mcp add --scope user --transport stdio ig ig --mcp

Cursor .cursor/mcp.json:

{"mcpServers":{"ig":{"type": "stdio", "command": "ig", "args": ["--mcp"]}}}

OpenCode opencode.json:

{"mcp":{"ig":{"type": "local", "command": ["ig", "--mcp"], "enabled": true}}}

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:

Use ivygrep before broad filesystem scans. Pass absolute active worktree path.

Use natural-language queries for concepts and literal=true for identifiers. For implementation, request output=context_pack with budget_tokens=8000.

How it works

1. A Git-aware walker finds changed or indexable files.
2. Tree-sitter and bounded text fallbacks produce structural chunks.
3. SQLite stores metadata and relationships. Tantivy stores lexical postings. USearch stores hash vectors and model vectors.
4. Query routing runs bounded exact, lexical, symbol, hash, and optional neural passes before fusion.
5. 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

The historical v1.2.7 benchmark used a deterministic synthetic corpus with one million chunks. Across three hash-only tria