What is Zvec-Grep (zg)?
Zvec-Grep, run as zg, indexes a workspace and answers searches by exact match, BM25 keyword ranking, vector similarity or a fused hybrid, returning ranked passages with paths, symbols and line numbers. It is built on the zvec vector database and serves both a command line and a local MCP server. By default agents see a single tool, zvec_grep_search, meant for questions where the wording or location is unknown; a full toolset adds rg, index management and status tools.
It is Apache-2.0, published on npm as @zvec/zvec-grep, and runs on macOS, Linux and Windows. Version 0.3.0, released on 3 November 2026, rebuilt the core in Rust. The repository has about 4,260 stars and 92 open issues and pull requests, and the npm package had about 12,189 downloads in the last month.
How to install Zvec-Grep (zg)
npm install -g @zvec/zvec-grep --allow-scripts=@zvec/zvec-grep && zg --install --target claudeIs Zvec-Grep (zg) worth it?
The design choice that matters is restraint. Where several rival code-context servers expose many tools, zg's default agent toolset is one, zvec_grep_search, and its docs tell the agent to keep using its own grep for exact words, filenames and regexes. The search itself fuses vector similarity for meaning with BM25 to anchor identifiers, so a question such as where user permissions are checked can land on the right function when nobody knows its name.
The privacy defaults are carefully drawn. Indexes live in .zvec-grep under the project, models in ~/.zvec-grep/models, and the default embedding model, potion-code-16m-v2, runs locally; eleven local models are listed, from 16m-parameter Model2Vec to Qwen3 Embedding 0.6B in GGUF. The three remote Qwen models need an API key and, separately, a consent grant: a key alone does not authorise sending workspace content, which takes --allow-remote or a workspace-scoped auth grant. The optional HTTP server listens on 127.0.0.1:7999 with authentication off by default on loopback; a token file turns bearer authentication on.
The 0.3.0 rewrite in Rust is a large change for a young project. On the maintainers' own test across 75,128 documents, package size fell from 167.5 MiB to 34.3 MiB, total indexing time from 219.13 s to 77.84 s, peak memory by 53.2% and MCP search latency from 20.93 ms to 14.88 ms. Those are vendor figures, as are the A/B agent benchmarks with Claude Code and Codex, and the README itself says results vary by model and run. With 92 open issues and pull requests and an index that must be rebuilt whenever the embedding model changes, it rewards a trial on one repository before it becomes the team default.
Where it earns its place
A backend developer new to a 300,000-line Django codebase
Find where a business rule is enforced when the function name is unknown
Run zg --index once, install into Claude Code with zg --install --target claude, and let the agent call zvec_grep_search before falling back to grep. Free with a local model; indexing time scales with repository size.
A policy analyst with a folder of reports and notes
Search documents by meaning from the terminal without an agent
Index with local/potion-retrieval-32m for English documents and query with zg --preview detail. Results come back ranked with file and line references; nothing leaves the laptop.
A platform team rolling out agent tooling to 20 engineers
Give every engineer the same semantic search across editors
Script zg --install for the team's targets (codex, claude, cursor, vscode) and keep the default one-tool toolset. If a shared Qwen model is wanted, grant remote embedding per workspace rather than globally.
Before you commit
- Setup
- npm install -g @zvec/zvec-grep --allow-scripts=@zvec/zvec-grep, then zg --index in the project and zg --install --target <client>. Restart the agent afterwards. The index is stored in .zvec-grep under the project root.
- Integrations
- Install targets include codex, claude, qwen, qoder, opencode, cursor, copilot, vscode, grok and pi. MCP over stdio by default, or HTTP via zg --server on. --mcp-toolset full adds rg, index and status tools.
- Data and privacy
- Files, indexes and local models stay on the machine. Remote Qwen embeddings send authorised workspace content and queries to the provider only after --allow-remote or a workspace auth grant, which can be revoked.
- Cost at scale
- Free with local models. Remote Qwen embeddings are billed by the provider per DashScope's pricing, which zg's docs do not list.
- Limits
- Text only, even with multimodal embedding models. Switching model or endpoint requires a rebuild. The HTTP server on 127.0.0.1:7999 has authentication off by default on loopback.
What’s good
- One default MCP tool keeps agent context small
- Local embedding models by default; nothing leaves the machine
- Remote embeddings need an explicit consent grant
- One-command install for Claude, Codex, Cursor and others
What’s not
- Benchmarks are the maintainers' own
- 92 open issues and PRs after a ground-up Rust rewrite
- Changing the embedding model means a full re-index
- Local HTTP server has no auth by default
Best for
Developers and researchers who want their coding agent to find code and documents by meaning without shipping the repository to an embedding API.
Zvec-Grep (zg) alternatives
Zvec-Grep (zg): common questions
- Is Zvec-Grep (zg) worth it?
- A well-judged local search tool for agents that keeps its MCP surface to one tool and makes remote embeddings an explicit opt-in, not a default. We rate it 4.0 out of 5.
- How much does Zvec-Grep (zg) cost?
- Free and open source (Apache-2.0). Local embedding models are free; the optional Qwen remote embeddings need a DashScope API key and are billed by that provider.
- What are the downsides of Zvec-Grep (zg)?
- Benchmarks are the maintainers' own; 92 open issues and PRs after a ground-up Rust rewrite; changing the embedding model means a full re-index; local HTTP server has no auth by default.
- Who is Zvec-Grep (zg) best for?
- Developers and researchers who want their coding agent to find code and documents by meaning without shipping the repository to an embedding API.
- How much does Zvec-Grep (zg) cost for a team or in production?
- Free with local models. Remote Qwen embeddings are billed by the provider per DashScope's pricing, which zg's docs do not list.
- Is Zvec-Grep (zg) safe for company data?
- Files, indexes and local models stay on the machine. Remote Qwen embeddings send authorised workspace content and queries to the provider only after --allow-remote or a workspace auth grant, which can be revoked.
- What are the best Zvec-Grep (zg) alternatives?
- The closest alternatives we have reviewed are Serena, CodeGraph, Semble and Project RAG.
Answers checked Nov 6, 2026.
Make Zvec-Grep (zg)? Show this rating on your site
