convez.ai
MCP ServerBusca & PesquisaIntermediário
bvolpato

ivygrep - Busca Semântica de Código

bvolpato/ivygrep

Busca semântica de código local com IA, sem uploads de dados

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que implementa busca semântica em código usando inferência local, sem enviar dados para a nuvem. Permite fazer perguntas em linguagem natural e obter resultados de código relevantes, ideal para navegação e compreensão de bases de código grandes.

Instalação

$npx convez-ai bvolpato/ivygrep

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
7
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 2 dias
Versão
v1.3.6
Issues abertas
2
Contribuidores
3

Casos de uso

  • Navegar e compreender grandes bases de código rapidamente
  • Encontrar padrões de código e implementações similares
  • Integrar buscas semânticas em fluxos de desenvolvimento com Claude

Veredito

Ferramenta sólida para buscas semânticas locais sem dependências de API externas. Implementação em Rust garante performance, mas exige indexação prévia e é mais voltada para desenvolvedores que precisam explorar código complexo.

README

A tradução para o português deste README ainda está na fila.


⚡ Quick Start

Install via Homebrew (recommended):

brew tap bvolpato/tap
brew install bvolpato/tap/ivygrep

Install a pre-built binary:

tag=$(curl -fsSL https://api.github.com/repos/bvolpato/ivygrep/releases/latest | sed -n 's/.*"tag_name": "\(v[^"]*\)".*/\1/p')
case "$(uname -s)-$(uname -m)" in
  Linux-x86_64) target=linux-x86_64-musl ;;
  Linux-aarch64|Linux-arm64) target=linux-aarch64-musl ;;
  Darwin-x86_64) target=macos-x86_64 ;;
  Darwin-arm64) target=macos-aarch64 ;;
  *) echo "unsupported platform: $(uname -s)-$(uname -m)" >&2; exit 1 ;;
esac
curl -fsSL "https://github.com/bvolpato/ivygrep/releases/download/${tag}/ivygrep-${tag}-${target}.tar.gz" \
  | tar xz --strip-components=1 "ivygrep-${tag}-${target}/ig"
mkdir -p ~/.local/bin
install -m 0755 ig ~/.local/bin/ig

Build from source:

git clone https://github.com/bvolpato/ivygrep.git && cd ivygrep
./build.sh
install -m 0755 ./target/release/ig ~/.local/bin/ig

Developer targets:

./build.sh --help
./test.sh --help
./bench.sh --help

./build.sh          # release binary
./build.sh --features accelerate,metal  # opt-in macOS Metal neural inference
./build.sh --features cuda  # opt-in Linux CUDA neural inference
./test.sh --quick   # fast local check
./test.sh           # fmt, clippy, unit/integration tests
./bench.sh          # critical Criterion benchmark, no stale local baseline comparison

Your first search:

ig "authentication flow"            # auto-indexes on first run, then searches
ig "error handling" src/api/         # scope to a directory
ig --all "database migrations"      # search across all indexed projects

That's it. No config files, no setup wizards, no prompts, no API keys. On first run, ig auto-indexes the workspace and spawns a background daemon for incremental updates. Neural mode downloads its model artifacts into the Hugging Face cache on first use; --hash and hash-only builds require no model download.


🤖 MCP Server — Supercharge Your AI Agent

ivygrep is the retrieval layer your coding agent is missing. Instead of stuffing entire files into context, your agent pulls only the relevant code chunks natively.

ig --mcp    # starts MCP server on stdio

One-line setup for agents:

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

Or add to ~/.claude.json:

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

Add to .cursor/mcp.json or ~/.cursor/mcp.json:

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

Then refresh MCP servers in Cursor settings.

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

Or add to ~/.gemini/settings.json:

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

OpenCode: opencode mcp add -> Choose Local and set command to ig --mcp.

Codex: Run codex mcp add ig -- ig --mcp or add to ~/.codex/config.toml.


🤔 What is ivygrep?

ivygrep (ig) is a local-first code search tool that understands natural language. It combines lexical search (like grep/rg) with semantic vector search — so you can search your code the way you think about it.

Traditional tools require you to know exactly what you're looking for. ivygrep lets you search with intent.

Featuregrep / rgGitHub Searchivygrep
Works offline✅❌✅
Natural language queries❌⚠️✅
Semantic understanding❌❌✅
Warm indexed query latency✅❌✅
Privacy-first (no upload)✅❌✅
Git-native (worktrees, branches)❌❌✅
Structural code chunking❌❌✅
Incremental indexing❌❌✅
MCP server for AI agents❌❌✅

🌍 45 Language/File Types Supported

ivygrep indexes and structurally chunks 45 language/file types today:

  • Tree-sitter AST chunking (21 languages): Rust, Python, Go, JavaScript, TypeScript/TSX, Java, C, C++, C#, Scala, PHP, Ruby, Swift, Bash, Haskell, OCaml, Lua, Dart, Objective-C, Perl, Starlark macros and targets in very large BUILD-like sources

  • Heuristic structural chunking: the remaining supported languages below

  • Systems: Rust, C, C++, Zig, Nim

  • Backend: Python, Go, Java, Kotlin, Scala, C#, Ruby, PHP, Perl, Groovy

  • Web & Mobile: JavaScript, TypeScript, HTML, CSS, GraphQL, Swift, Dart, Objective-C

  • Functional: Haskell, OCaml, Elixir, Erlang, Clojure

  • Data, Scripting & Config: R, Julia, Bash/Shell, PowerShell, Lua, SQL, Protobuf, Thrift, Terraform, Starlark/Bazel, Dockerfile, Makefile, Markdown, XML, TOML/YAML/INI/env config, JSON, plain text

Unknown extensions are auto-detected and indexed as text.


🚀 Performance & Speed

Fresh release-readiness validation used a Linux kernel checkout with 93,502 indexed files and 4,419,660 chunks:

ScenarioMetricResult
Fresh lexical-first Linux kernel indexfull rebuild~270 sec
Large-repo natural queryprocess-cold p95~137 ms
Warm daemon identical-query replayend-to-end p95~79 ms
Warm daemon distinct queriesend-to-end p95~116 ms
Portable Linux intent relevance13 labeled queries41.20
Best retained dedicated-host daemon runidentical-query p95~4.9 ms
Historical eager-vector Linux kernel indexfull rebuild~27.3 min
Lexical-first scoped stress probe10,501 files~3 sec
Warm daemon correctness guarddaemon/local hits20 / 20

The daemon benchmark now reports warmed distinct-query latency separately from identical-query cache replay. Latency depends on CPU, storage, and virtualization; the single-digit result is a retained dedicated-host benchmark, not a universal claim. Benchmark writeups and charts live under docs/benchmarks/.

Indexing commits BM25/literal search first. A load-aware background subprocess builds hash ANN vectors, then upgrades to local neural vectors with Candle (AllMiniLML6V2). macOS release builds use Accelerate-backed CPU math; Metal is available as an opt-in local build while its background throughput is tuned.

Relevance evaluation separates foreground readiness from post-background hash quality:

uv run scripts/eval_relevance.py
uv run scripts/eval_relevance.py --enhance-hash

🏗️ Architecture & Git-Native Intelligence

ivygrep deeply understands git. This is a core design decision, not an afterthought:

  • Worktree overlays: Doesn't duplicate indexes contextually. Creates thin overlays mapping divergent chunks.
  • Branch-switch deltas: Targets Merkle-diff re-indexes of only changed files upon branch switch.
  • Content-based deduplication: Byte-identical files are never re-indexed across branches.
  • .gitignore native: Respects rules automatically at every level.

Tech stack: tantivy (BM25), usearch (vector store), tree-sitter (AST), candle_embed / candle-core (local neural embeddings), xxh3 (SIMD hashes).


🔒 Security & Privacy

ivygrep runs search and embedding inference locally and never sends your code, queries, or index data to an external service. A few things worth knowing:

  • Where data lives: the index (which stores compressed source chunks in SQLite) and the daemon socket live under ~/.local/share/ivygrep (or $XDG_DATA_HOME/$IVYGREP_HOME). The index directory is 0700 and the daemon socket 0600, and the daemon verifies the connecting peer's uid — so other local users on a shared host can't read your indexed code or reach the daemon.
  • Model download: neural mode uses hf-hub to download AllMiniLM-L6-v2 model assets on first use and caches them under $HF_HOME or ~/.cache/huggingface. Use --hash or a --no-default-features build when no model-network access is permitted.
  • Inference backend: macOS release binaries execute locally with Accelerate-backed CPU math; portable Linux release binaries execute locally on CPU. Source builds can opt into local Metal with --features accelerate,metal or CUDA with --features cuda on a compatible installation. The CUDA build does not require cuDNN. If nvidia-smi cannot report compute capability, build.sh and test.sh infer CUDA_COMPUTE_CAP=120 for RTX 50/Blackwell hosts; set CUDA_COMPUTE_CAP explicitly for other affected GPUs. ig --status reports the recorded backend that last generated neural vectors.
  • Secrets in your repo: ivygrep indexes file contents, including config/dotfiles (e.g. .env) unless they're gitignored. Those contents are stored in the local index and can appear in search snippets. Keep secrets out of the workspace or in .gitignore.
  • MCP scope: the ig_search MCP tool only searches the workspace at the provided path — it cannot search across other indexed projects.

🔧 CLI Reference

# Core workflow
ig "your query"                    # search current workspace
ig "query" ~/other/project         # search a different workspace
ig --add .                         # register & index a workspace
ig --rm .                          # unregister a workspace
ig --status                        # show workspace health & embedding status
ig --doctor                        # inspect index health for the current workspace
ig --doctor --fix                  # rebuild a broken or stale index

# Search modes
ig --interactive "query"             # interactive TUI with file/snippet browsing
ig --literal "fn_name"               # fast exact-match search (index-backed)
ig --hash "query"                  # force hash embeddings (skip neural)

# Output control
ig -n 5 "query"                    # limit to 5 files
ig -C 4 "query"                    # 4 lines of context
ig --type rust "query"             # filter by language
ig --include "*.rs,*.go" "query"   # include globs
ig --exclude "vendor/**" "query"   # exclude globs
ig --json "query"                  # machine-readable JSON
ig --first-line-only "query"       # compact grep-style output
ig --file-name-only "query"        # file paths only

# Daemon & server
ig --daemon                        # start background watcher
ig --mcp                           # start MCP server (stdio)

🧪 Development

./test.sh           # fmt, ShellCheck, clippy, Rust and Python harness tests
./build.sh --locked # release binary, Cargo.lock unchanged
./build.sh --locked --features accelerate,metal  # opt-in macOS Metal neural binary
./build.sh --locked --features cuda  # opt-in Linux CUDA neural binary
./bench.sh          # critical Criterion benchmark, no stale local baseline comparison

The test suite covers unit tests, CLI snapshots, concurrency, golden queries, labeled relevance metrics, incremental CRUD, MCP, daemon recovery, git/worktree behavior, property-based Merkle invariants, and benchmark guards. Benchmark output reports per-operation latency; short-looking numbers are repeated inside Criterion so actual timed samples remain long enough to be stable.

End-to-end procedures

./build.sh
./scripts/e2e_procedures.sh --binary ./target/release/ig
python3 scripts/check_daemon_equivalence.py \
  --skip-build \
  --binary ./target/release/ig \
  --bench-home /tmp/ivygrep-daemon-equivalence

# Opt-in macOS Metal backend validation (downloads local model artifacts on first run)
./build.sh --locked --features accelerate,metal
./scripts/e2e_neural_backend.sh --binary ./target/release/ig --expect-backend "Candle Metal"

# Opt-in Linux CUDA backend validation (downloads local model artifacts on first run)
./build.sh --locked --features cuda
./scripts/e2e_neural_backend.sh --binary ./target/release/ig --expect-backend "Candle CUDA"

These smoke tests run against throwaway projects and isolated IVYGREP_HOME directories; the neural backend check embeds fixture text locally and verifies recorded backend reporting.

Stress testing

./scripts/bootstrap_stress_fixtures.sh
./test.sh --stress

Roadmap

  • More Tree-sitter languages: expand the AST pipeline to Kotlin, SQL, and additional grammars as high-quality tree-sitter parsers mature.

  • Symbol retrieval: store symbol tables during chunking, add a second index for definitions, references, and call edges. Enable symbol, refs, and callers workflows without replacing the current hybrid text retrieval.

  • Editor integrations: VS Code extension and Neovim telescope plugin for in-editor semantic search.

  • Windows support: resolve usearch/simsimd MSVC compatibility for native Windows builds.

  • Background job resilience: richer queue diagnostics and resumable worker state across daemon restarts.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.


Ver o original no GitHub

Bom para

Relacionados