Qwen Developers have released zg (zvec-grep), an open-source tool that combines ripgrep, BM25, and vector search into a single local-first interface.
The code is available under an Apache 2.0 license within the zvec-ai GitHub organisation. It installs via npm as @zvec/zvec-grep and runs on Node.js 22 or newer across macOS, Linux, and Windows. The default model requires no GPU, though the software is designed for commercial use.
One index, four retrieval routes
Once zg indexes a workspace, it offers four distinct ways to query the data. The default hybrid route merges semantic intent with lexical anchors. The --fts flag provides BM25-ranked results for exact terms. The --vector option searches for conceptual similarity without lexical ranking. The --rg route performs exhaustive literal or regex matching and requires no index at all, making it useful for repositories that have not yet been indexed.
Indexed results live in a hidden directory at <root>/.zvec-grep/. The tool automatically excludes .git and .zvec-grep folders, along with standard build, cache, and log directories, respecting the repository’s own ignore rules as well. Running zg index updates the index incrementally. Changing the embedding model requires an explicit --rebuild flag because vector spaces from different models are incompatible, even if they share the same dimensions.
Indexed results report a freshness state of fresh or possibly_stale. This allows an agent to act on a sufficient result without running a status preflight first.
The MCP surface agents actually see
Running zg install detects Codex, Claude Code, Cursor, and OpenCode on the machine and sets up local MCP integration. The server communicates via Streamable HTTP MCP on a loopback-only endpoint at http://127.0.0.1:7999/mcp, with optional bearer authentication.
The design prioritises restraint. According to the MCP guide, the default agent toolset exposes exactly two tools: zvec_grep_search for when the intent is known but the exact string is not, and zvec_grep_rg for when a symbol, path, or regex is known. Index lifecycle management remains with the CLI. A six-tool compatibility set that adds index creation, deletion, status checks, and server status exists but is opt-in through zg server on --mcp-toolset full. The documentation states that an agent must never silently create, rebuild, or delete a persistent index.
Output is shaped for context economy. Results return grouped by file with line spans, and indexed source previews are omitted by default unless requested. The tool also rejects output-changing ripgrep flags such as --json, --count, -l, and --vimgrep to maintain a compact result format.
Embeddings run on device by default
The embedding catalog documents ten local models and three remote Qwen endpoints. The quickstart default, local/potion-code-16m-v2, is a Model2Vec static model with a 256-dimension output and an 8,192-token input limit. Because it uses static vector lookup, selecting a GPU does not speed up the process. Heavier local options include jina-embeddings-v2-base-code, embeddinggemma-300m, and qwen3-embedding-0.6b. Remote options run to qwen/qwen3.7-text-embedding at 128,000 input tokens and the multimodal qwen/qwen3-vl-embedding.
Remote use is gated. Configuring a provider credential does not authorise data transfer; that requires either --allow-remote for a single command or a signed workspace grant via zg auth grant, which can be revoked with zg auth revoke. The launch post cites eleven on-device models against ten in the current documentation, a small discrepancy worth noting.
What the benchmark numbers say
The evaluation figures appear in the launch post, not in the repository, where the benchmarks section remains a placeholder. Both runs were paired A/B tests holding agent, model, prompt, runtime, and task constraints fixed, with the zg condition adding only a prebuilt index, MCP tools, and usage guidance. Index build cost is excluded from the tables.
On a 20-question SWE-QA-Bench sample, zg cut tool calls by more than half and input tokens by nearly half while raising the Judge score by 1.50 points. On an 80-question BrowseComp-Plus sample, accuracy moved from 98.67% to 99.00% while input tokens fell 37.56%, tool calls 43.52%, and agent time 38.58%. Separately, indexing the Django repository (3,457 files) is reported to finish in under 30 seconds on an Apple M4 Pro.
Sample sizes of 20 and 80 questions are small, and the reported reductions come from the vendor’s own runs, so independent replication is the obvious next step.
What it means
Developers and agents gain a single interface that handles literal text search, keyword matching, and semantic understanding without needing to manage multiple tools. The reduction in tool calls and tokens suggests faster execution and lower costs for coding agents. The explicit separation between the agent’s search tools and the index lifecycle prevents accidental corruption of the workspace data. Remote embedding usage remains controlled, ensuring data stays local unless explicitly authorised.
