{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/logo.png\" alt=\"ivygrep logo\" width=\"150\" />\n</p>\n\n<p align=\"center\">\n  <strong>Turn coding tasks into bounded, branch-aware context.</strong><br/>\n  Search, indexing, and context generation run locally. Optional model profiles download pinned assets on first use.\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/bvolpato/ivygrep/actions/workflows/ci.yml\"><img src=\"https://github.com/bvolpato/ivygrep/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /></a>\n  <a href=\"https://github.com/bvolpato/ivygrep/actions/workflows/security.yml\"><img src=\"https://github.com/bvolpato/ivygrep/actions/workflows/security.yml/badge.svg\" alt=\"Security\" /></a>\n  <a href=\"https://github.com/bvolpato/ivygrep/actions/workflows/relevance.yml\"><img src=\"https://github.com/bvolpato/ivygrep/actions/workflows/relevance.yml/badge.svg\" alt=\"Relevance\" /></a>\n  <a href=\"https://github.com/bvolpato/ivygrep/releases/latest\"><img src=\"https://img.shields.io/github/v/release/bvolpato/ivygrep?color=34d058\" alt=\"Latest release\" /></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"MIT license\" /></a>\n</p>\n\n<p align=\"center\">\n  <img src=\"assets/hero-workflow.svg\" alt=\"ivygrep search followed by a bounded task-context pack\" width=\"800\" />\n</p>\n\n<p align=\"center\">\n  <a href=\"https://bvolpato.github.io/ivygrep/\">Website</a> ·\n  <a href=\"docs/architecture.md\">Architecture</a> ·\n  <a href=\"https://bvolpato.github.io/ivygrep/benchmarks/\">Benchmarks</a> ·\n  <a href=\"CONTRIBUTING.md\">Contributing</a> ·\n  <a href=\"https://github.com/bvolpato/ivygrep/discussions\">Discussions</a>\n</p>\n\n## Search and build context\n\n```bash\n# Find code by intent\nig \"where is refresh token rotated?\"\n\n# Build context from code and current changes\nig context \"fix refresh-token races\" --since main --budget 8000\n```\n\nAbridged output:\n\n```text\n# ivygrep context\nBudget: 7,642 / 8,000 estimated tokens\nCoverage: 7 files | 2 primary | 1 definitions | 1 dependencies | 0 dependents | 2 callers | 0 references | 1 tests | 0 config | 0 docs\nCandidates: 31 retrieved | 14 selected\n## Evidence\n### 1. src/auth/refresh.rs:118-166 [primary, definition]\nWhy: task anchor; changed implementation.\nSignals: lexical, symbol, git change.\n```\n\nSearch answers where. Context answers what an agent needs to change safely.\n\nThe context command combines task anchors with commits since the branch point, staged and dirty files,\nissue or trace paths, and indexed relationships. It returns one bounded Markdown pack with path, lines,\nrole, reason, and retrieval signals. `--since` requires a Git worktree; omit it for non-Git directories.\n\n## Install\n\n```bash\n# Homebrew on macOS or Linux\nbrew install bvolpato/tap/ivygrep\n\n# Release installer on macOS or Linux\ncurl -fsSL https://raw.githubusercontent.com/bvolpato/ivygrep/main/install.sh | sh\n```\n\n```powershell\n# WinGet on Windows\nwinget install --id BrunoVolpato.ivygrep --exact\n\n# Release installer on Windows\nirm https://raw.githubusercontent.com/bvolpato/ivygrep/main/install.ps1 | iex\n```\n\nInstallers 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.\n\nBuild from source on macOS or Linux:\n\n```bash\ngit clone https://github.com/bvolpato/ivygrep.git && cd ivygrep\n./build.sh\nmkdir -p ~/.local/bin\ninstall -m 0755 target/release/ig ~/.local/bin/ig\n```\n\n## Search\n\nThe first query indexes the current repository. The daemon then watches for changes and updates the index incrementally.\n\n```bash\nig \"where is authentication handled?\"       # hybrid semantic + lexical\nig --literal \"handleAuth\"                    # exact indexed lookup\nig --symbol calculate_tax                    # definitions\nig --refs calculate_tax                      # references and calls\nig --callers calculate_tax                   # caller chunks\nig \"database migrations\" src/api/           # path scope\nig --all \"retry policy\"                      # all indexed projects\nig --interactive \"auth flow\"                 # terminal UI\nig --web \"auth flow\" .                       # local Web UI\n```\n\nUseful controls include `-n` for result files, `-C` for context lines, `--type`\nfor language, `--include`/`--exclude` path globs, `--lexical-only`, `--hash`, and `--json`. `--hash`\nuses lightweight local embeddings for faster startup and no model download,\nwith lower semantic quality. Run `ig --help` for full reference.\n\nOn macOS laptops, background neural enhancement pauses on battery power (`ig --status`\nshows `Paused: Battery Power`); set `IVYGREP_ENHANCE_ON_BATTERY=1` to keep it running.\nThe lightweight hash tier keeps computing on battery so semantic results stay available.\n\n## Search notes and memories\n\nIndex notes once. Watcher keeps them current, and queries use local semantic + lexical search by default:\n\n```bash\nig --add ~/notes --wait-for-enhancement\nig -n 20 \"what did we decide about cache invalidation?\" ~/notes\n```\n\nPublic [MemoryQuest results](https://bvolpato.github.io/ivygrep/benchmarks/public-memory-retrieval.html): 74.9% recall@20 at 87.63 ms warm p95. Benchmark measures retrieval only; answer accuracy is outside scope.\n\n## Connect coding agents\n\nCodex and Claude Code packages install MCP configuration plus focused task-context skill:\n\n```bash\ncodex plugin marketplace add bvolpato/ivygrep\ncodex plugin add ivygrep@ivygrep\n\nclaude plugin marketplace add bvolpato/ivygrep\nclaude plugin install ivygrep@ivygrep\n```\n\nAutomatic setup detects the client, preserves existing configuration, writes the absolute `ig` path, verifies the MCP handshake, and runs a search:\n\n```bash\nig agent install claude\nig agent install codex\nig agent install cursor\nig agent doctor\n```\n\nRestart an open client after installation. Manual MCP setup is also available:\n\n```bash\nclaude mcp add -s user ig -- ig --mcp\ncodex mcp add ig -- ig --mcp\ngemini mcp add --scope user --transport stdio ig ig --mcp\n```\n\nCursor `.cursor/mcp.json`:\n\n```json\n{\"mcpServers\":{\"ig\":{\"type\": \"stdio\", \"command\": \"ig\", \"args\": [\"--mcp\"]}}}\n```\n\nOpenCode `opencode.json`:\n\n```json\n{\"mcp\":{\"ig\":{\"type\": \"local\", \"command\": [\"ig\", \"--mcp\"], \"enabled\": true}}}\n```\n\nAgents 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.\n\nContext packs can include definitions, callers, references, dependencies, dependents, tests, configuration, and docs.\n\nSetup guides: [Codex](https://bvolpato.github.io/ivygrep/integrations/codex.html), [Claude Code](https://bvolpato.github.io/ivygrep/integrations/claude-code.html), [Cursor](https://bvolpato.github.io/ivygrep/integrations/cursor.html), [Gemini CLI](https://bvolpato.github.io/ivygrep/integrations/gemini-cli.html), [OpenCode](https://bvolpato.github.io/ivygrep/integrations/opencode.html), and [MCP](https://bvolpato.github.io/ivygrep/integrations/mcp.html).\n\nRecommended agent instruction:\n\n```text\nUse ivygrep before broad filesystem scans. Pass absolute active worktree path.\nUse natural-language queries for concepts and literal=true for identifiers.\nFor implementation, request output=context_pack with budget_tokens=8000.\n```\n\n## How it works\n\n1. A Git-aware walker finds changed or indexable files.\n2. Tree-sitter and bounded text fallbacks produce structural chunks.\n3. SQLite stores metadata and relationships; Tantivy stores lexical postings; USearch stores hash and optional model vectors.\n4. Query routing runs bounded exact, lexical, symbol, hash, and optional neural passes before fusion.\n5. Context expands primary hits through code relationships and recent changes,\n   then trims rendered evidence to requested token budget.\n\nFresh indexing publishes lexical results before vector enhancement. Worktrees\nreuse base index and store only divergent chunks and tombstones. Partial\nworkspace failures return warnings with valid hits; complete failure errors.\n\nivygrep supports 45 language and file types. Twenty-four use Tree-sitter AST chunking:\nRust, Python, Go, JavaScript, TypeScript, Java, C/C++, C#, Kotlin, Scala, PHP,\nRuby, Swift, Elixir, Zig, Bash, Haskell, OCaml, Lua, Dart, Objective-C, Perl, and Starlark.\n\nRead [architecture](docs/architecture.md) for storage, commit order, retrieval,\nworktrees, protocols, security boundaries, and module ownership.\n\n## System performance\n\nOn 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.\n\n[Current-release evidence](https://bvolpato.github.io/ivygrep/benchmarks/public-million-current.json) · [Million-chunk methodology and historical paired study](https://bvolpato.github.io/ivygrep/benchmarks/public-million.html) · [Full benchmark dashboard](https://bvolpato.github.io/ivygrep/benchmarks/evidence-dashboard.html)\n\n## Local and private\n\nRuntime source, queries, embeddings, results, and indexes stay local. Neural\nprofiles download pinned model assets on first use unless cache is already\npopulated. Use `--hash`, `./build.sh --hash-only`, or\n`cargo build --locked --no-default-features` to avoid model downloads.\n\n`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.\n\nReport vulnerabilities through a [private security advisory](SECURITY.md). Release archives include checksums, SBOMs, and provenance.\n\n## Contribute\n\n```bash\n./test.sh --quick\n./test.sh\n./bench.sh\n```\n\nStart with a [good first issue](https://github.com/bvolpato/ivygrep/labels/good%20first%20issue), read [CONTRIBUTING.md](CONTRIBUTING.md) and [architecture](docs/architecture.md),\nor discuss an idea in [Discussions](https://github.com/bvolpato/ivygrep/discussions).\n\nMIT licensed. Maintained by [Bruno Volpato](https://github.com/bvolpato).\n",
  "bytes": 10608,
  "sha": "a9651986f59eb98338da1288b1169044ae3674654e210851c1b7bfd53dd416ce",
  "repo_slug": "bvolpato/ivygrep",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bvolpato_ivygrep_d0fe50e2/readme"
}