ivygrep

[ivygrep logo]

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.

[CI] [Security] [Relevance] [Latest release] [MIT license]

[ivygrep search followed by a bounded task-context pack]

Website · Architecture · Benchmarks · Contributing · Discussions

Search and build context

# Find code by intentig "where is refresh token rotated?"
# Build context from code and current changesig context "fix refresh-token races" --since main --budget 8000

Abridged output:

# ivygrep contextBudget: 7642 / 8000 estimated tokensCoverage: 7 files | 2 primary | 1 definitions | 1 dependencies | 0 dependents | 2 callers | 0 references | 1 tests | 0 config | 0 docsCandidates: 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 Linuxbrew install bvolpato/tap/ivygrep
# Release installer on macOS or Linuxcurl -fsSL https://raw.githubusercontent.com/bvolpato/ivygrep/main/install.sh | sh

# WinGet on Windowswinget install --id BrunoVolpato.ivygrep --exact
# Release installer on Windowsirm 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.shmkdir -p ~/.local/bininstall -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 + lexicalig --literal "handleAuth"                    # exact indexed lookupig --symbol calculate_tax                    # definitionsig --refs calculate_tax                      # references and callsig --callers calculate_tax                   # caller chunksig "database migrations" src/api/           # path scopeig --all "retry policy"                      # all indexed projectsig --interactive "auth flow"                 # terminal UIig --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-enhancementig -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/ivygrepcodex plugin add ivygrep@ivygrep
claude plugin marketplace add bvolpato/ivygrepclaude 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 claudeig agent install codexig agent install cursorig agent doctor

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

claude mcp add -s user ig -- ig --mcpcodex mcp add ig -- ig --mcpgemini 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 trials, median warm CLI p95 was 6.19 ms. Controlled indexing reached 150,576 chunks/s. The final index used 0.42 GiB. These results measure scale and footprint, not retrieval quality or coding-task accuracy. They do not describe the current neural model under concurrent load.

The resource and latency report measures the released binary with both static model profiles. It includes repeated enhancement measurements, forced-neural p99, eight MCP clients, RSS, CPU, and disk writes. The model-screening report remains separate because it used one repetition.

Historical scale measurements (v1.2.7) · Million-chunk methodology · Full benchmark dashboard

The source implementation limits cached results to 64 MiB and cached neural queries to 4 MiB. Parsed context input has a shared 32 MiB cache. Content digests prevent reuse after a file changes. Idle search contexts share a 256 MiB estimated budget. Each index run has a 32 MiB estimated budget for queued payloads. A large file can exceed the indexing target when it runs alone. These budgets do not cap total process RSS. See memory budgets and diagnostics for scope and timing commands.

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. Its Web API requires a session token, including on loopback. The printed URL contains that token. Keep terminal output and logs that capture it private. The browser opens through an owner-only redirect file in the app home. This keeps the token out of process arguments. To skip the browser, set IVYGREP_NO_BROWSER=1.

Non-loopback listeners use plain HTTP. Use a trusted network, Tailscale, or an encrypted tunnel. Never expose the listener directly to the internet. Indexed file contents can appear in snippets. This includes dotfiles that your ignore rules permit.

Report vulnerabilities through a private security advisory. Release archives include checksums, SBOMs, and provenance.

Data and configuration

Indexes and daemon state live in ~/.local/share/ivygrep on every OS (under %USERPROFILE% on Windows). IVYGREP_HOME overrides that path; otherwise a non-empty XDG_DATA_HOME selects $XDG_DATA_HOME/ivygrep. Model assets use the Hugging Face cache (HF_HOME, default ~/.cache/huggingface), which other tools may share.

There is no configuration file. Use CLI flags and the environment variables.

ig --status          # tracked workspaces, index health, vector coverage, disk usageig --rm ~/notes      # remove a saved index; defaults to current directoryig --gc              # remove indexes whose directory has been gone past the grace period

Starting with v1.3.1, a CLI search or context request, ig --interactive, or ig --add prompts before it builds an index for your home directory, a directory containing it, or the filesystem root. Confirm with y or yes. Without an interactive terminal, the command stops unless you pass --yes. An already indexed, healthy directory does not prompt on a plain ig --add. ig --add --force rebuilds it, and --skip-gitignore may add ignored files, so those cases prompt too.

The daemon also removes the index of a directory that stays missing for seven days (IVYGREP_INDEX_GC_GRACE_SECS), and the overlay of a worktree removed with git worktree remove after ten minutes.

Troubleshooting, upgrade, and uninstall

ig --doctor          # diagnose index, daemon, watcher, and model healthig --doctor --fix    # repair a broken or stale indexig --add . --force   # rebuild current workspace index from scratchig hardware          # inspect detected hardware and matching build

Open the URL ig --web prints: a bare http://127.0.0.1:4747/ returns 401 until the browser has the session cookie that URL sets. If ig --web opens a page that cannot load its redirect file, as snap-packaged browsers on Ubuntu do for files under hidden directories, open the URL it prints. Under WSL, a Windows browser can load the redirect file only through an opener that translates Linux paths, such as wslview; otherwise open the printed URL.

Upgrade through the channel you installed from: brew upgrade ivygrep, winget upgrade --id BrunoVolpato.ivygrep --exact, or rerun the installer. The next command restarts a daemon from an older build; index format changes rebuild existing indexes once on first use.

To uninstall, run brew uninstall ivygrep or winget uninstall --id BrunoVolpato.ivygrep --exact, or delete ig from the installer directory (~/.local/bin or %LOCALAPPDATA%\ivygrep\bin unless IVYGREP_INSTALL_DIR was set). Then stop any running ig --daemon process and delete the data directory.

Contribute

./test.sh --quick./test.sh./bench.sh

Start with a good first issue, read CONTRIBUTING.md and architecture, or discuss an idea in Discussions.

MIT licensed. Maintained by Bruno Volpato.