v1.2.6

Turn coding tasks into
focused repository context.

One search for discovery. One implementation map from the task, current Git changes, and linked code. Every selection is explained. Everything stays local.

Install ivygrep Source Context Packs
Terminal - ig
# Search by intent, then gather task context.
$ ig "where is refresh token rotated?"
src/auth/refresh.rs:118
fn rotate_refresh_token(...) -> Result<Token>
$ ig context "fix refresh-token races" --since main --budget 8000
Context: 14 snippets, 7,642 tokens, 3 changed files
Coverage: definitions, callers, dependents, tests
Task + diff Current work included
Graph Relationships followed
8K Default token budget
0 Bytes uploaded
Task context

One task. One branch. One implementation map.

Not a longer result list. A bounded pack connecting current work to code an agent needs to understand before editing.

Current work becomes retrieval signal

ig context --since main combines task anchors with committed branch changes, staged and dirty files, untracked files, and paths found in an issue or stack trace. It follows dependencies, dependents, definitions, callers, references, tests, configuration, docs, and recent co-changes.

PrimaryDependenciesDependentsDefinitionsCallersReferences TestsConfigDocs

Each item includes exact lines, its role, why it was selected, and how it relates to the task.

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

# ivygrep context
Budget: 3842 / 8000 estimated tokens
Changes: 4 files from main...HEAD plus dirty worktree
Coverage: 7 files | primary | dependencies | dependents | definitions | tests

1. src/auth/refresh.rs:42-88 [primary, definition]
2. src/http/session.rs:117-145 [dependent, caller]
3. tests/refresh_token.rs:20-61 [test]

Branch-aware

Committed and uncommitted changes shape selection before graph expansion begins.

Relationship-aware

Owning code, callers, dependencies, tests, configuration, and docs stay connected.

Budget-aware

Selection, deduplication, and trimming produce one pack sized for the receiving agent.

Capabilities

Built for live repositories, not one-off searches

Task state, repository relationships, and incremental indexes stay connected across CLI, MCP, and Web.

🎯

Task-aware inputs

Combine a task, issue, trace, branch diff, staged files, and dirty worktree before selecting code.

🕸️

Repository relationships

Expand from task anchors through definitions, callers, references, dependencies, dependents, tests, configuration, docs, and recent co-changes.

📦

Bounded evidence

Token-aware selection and deduplication produce one pack with exact paths, lines, roles, reasons, and relationships.

🌿

Thin worktree overlays

Worktrees reuse the repository base index and store only divergent chunks and tombstones across lexical, vector, and relationship stores.

⚡

Incremental availability

Changed chunks update incrementally. Lexical results remain available while hash and neural vectors build in the background.

🧭

Exact and semantic

Move between natural-language intent, literal text, symbols, references, callers, paths, and project-wide search in one engine.

🔁

One context contract

CLI, JSON, MCP, and Web expose the same structured search results and task-context packs.

🔒

Local by design

No hosted inference or telemetry. Source, queries, embeddings, and indexes stay on your machine.

Web interface

Browse indexed workspaces

The local browser UI searches tracked workspaces, scopes results to a folder, and opens indexed files beside the result list.

Result cards show language icons, syntax-highlighted snippets, line markers, and selected-state highlighting. The file viewer highlights focused result lines and previews Markdown with a source toggle.

Loopback stays zero-config. A non-loopback bind prints an authenticated URL. On another device, replace only 127.0.0.1 with the server's LAN or Tailscale address and preserve the complete token=... query string. Open it directly and do not share it: the browser exchanges it for an HttpOnly session cookie, then removes it from the address. Restart the daemon to invalidate access.

Non-loopback serving uses plain HTTP: the token authenticates requests but does not encrypt source or results. Use a trusted network only, preferably Tailscale or an SSH tunnel. Never expose the port directly to the internet or untrusted Wi-Fi.

$ ig --web
$ ig --web "auth flow" .
$ ig --web --host 0.0.0.0 --port 4747
Architecture

How indexing and search fit together

BM25 and literal search are available first; background jobs add hash and neural vectors.

1

Lexical index

File chunks go into SQLite and Tantivy first, so search works before vector jobs finish.

2

Hybrid fusion

BM25, literal matches, symbols, paths, and vector hits combine through Reciprocal Rank Fusion.

3

Local vectors

The daemon adds hash vectors and locally cached 256-dimensional static-retrieval-v1 vectors in the background. macOS releases use Accelerate-backed CPU math; the shell installer can select Apple Silicon Metal or Linux CUDA archives when available.

Git-aware indexing

Worktrees share a base index. Branch switches re-index only changed files.

Worktree overlays

Each worktree references the shared base index. SQLite, lexical, and vector overlays store changed chunks and tombstones.

Branch-switch deltas

Merkle reconciliation re-indexes changed files. Content hashes skip byte-identical files across branches.

System evidence

Context stays practical at repository scale

Absolute measurements from a deterministic one-million-chunk corpus show local indexing and query paths at scale.

15.07 ms

Warm query p95

109,006 chunks/s

Controlled indexing

0.46 GiB

Final index size

These are system measurements, not agent outcomes. Hardware, repository shape, model, index state, and load affect absolute results.

Public million-chunk benchmark Benchmark dashboard

Language support

45 language/file types, 24 Tree-sitter ASTs

Tree-sitter sources get function/class-level chunks. Other supported files use heuristic chunks.

Tree-sitter AST 24 languages

Rust Python Go JavaScript TypeScript Java C C++ C# Scala Kotlin PHP Ruby Swift Elixir Zig Bash Haskell OCaml Lua Dart Objective-C Perl Starlark macros/targets

Heuristic chunking 21 more

Nim Groovy Erlang Clojure R Julia PowerShell SQL Protobuf Thrift GraphQL Terraform Dockerfile Makefile Markdown HTML CSS XML Config JSON Text
Model Context Protocol

MCP for coding agents

Use MCP search to find code. Set output=context_pack, optional since=main, and a token budget to build the same context pack available from CLI and Web.

One-command setup

The installer preserves existing configuration, verifies MCP, and runs a search.

Claude Code

ig agent install claude

Codex

ig agent install codex

Cursor

ig agent install cursor
ig agent doctor

Manual MCP setup

Claude Claude Code

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

OpenAI Codex

codex mcp add ig -- ig --mcp

Gemini Gemini CLI

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

Cursor Cursor

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

OpenCode

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

MCP search settings

Pass the absolute repository or worktree path to ig_search. Use a natural-language query for concepts, literal=true for identifiers, or output=context_pack with since=main and budget_tokens=8000 for implementation context.

The first search creates an index and starts incremental watching. Worktrees reuse one shared base index and store only divergent chunks and tombstones.

Codex guide Claude Code guide Cursor guide Gemini CLI guide OpenCode guide MCP Registry

MCP search flow

🤖
Agent sends query
"find error handling logic"
→
🔍
ig searches index
BM25 + Vector + Literal
→
📄
Returns top chunks
Function bodies, classes, imports
→
✅
Agent gets context
Without loading entire files
Open source

Contributing

Choose a scoped issue, run the relevant checks, and keep the pull request focused.

Start small

Pick a scoped issue with setup and validation guidance.

Good first issues

Discuss larger changes

Use Discussions for questions and designs that affect storage, ranking, or compatibility.

Discussions

Open a pull request

Follow the contributor guide and include the checks that cover the change.

Contributor guide
Get started

Install ivygrep

The installer selects CUDA on compatible NVIDIA Linux hosts and Metal on Apple Silicon. Run ig hardware to inspect the selected build.

Homebrew for macOS and Linux

$ brew install bvolpato/tap/ivygrep

Metal on Apple Silicon. Portable elsewhere.

Shell installer for Linux and macOS

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

Detects CUDA, Metal, and missing runtime libraries.

Windows PowerShell

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

Portable Windows build.

Quick start

1

Index your project

ig --add .
2

Search with natural language

ig "where is authentication handled?"
3

Find an exact identifier

ig --literal "handleAuth"
4

Browse in a local web UI

ig --web "auth flow" .
5

Configure an MCP client

ig agent install claude