zg (zvec-grep): One CLI That Combines ripgrep, BM25, and Vector Search

The Qwen Developer team has open-sourced zg (zvec-grep), a local-first search tool that combines ripgrep, BM25 full-text ranking, and semantic vector search behind one command-line interface. Published under the Apache 2.0 license and installable via npm as @zvec/zvec-grep, it targets both human developers and AI coding agents that burn excessive tool calls hunting through codebases. It requires Node.js 22 or newer, runs on macOS, Linux, and Windows, and needs no GPU with the default embedding model.

What happened

Detail	Value
Package name	@zvec/zvec-grep (npm)
License	Apache 2.0 (commercial use allowed)
Runtime requirement	Node.js 22 or newer
Platforms	macOS, Linux, Windows
MCP server endpoint	http://127.0.0.1:7999/mcp (loopback only)
Default embedding model	local/potion-code-16m-v2 (256-dim, 8,192-token limit, no GPU needed)
Django repo index time	Under 30 seconds on Apple M4 Pro (3,457 files)

zg indexes a workspace once, storing the index at <root>/.zvec-grep/, then offers four retrieval routes depending on what you already know about the target:

• Hybrid (default): combines semantic intent with lexical anchors.
• –fts: BM25-ranked full-text search for known exact terms.
• –vector: conceptual similarity with no lexical weighting.
• –rg: exhaustive literal or regex matching via ripgrep. This route requires no index at all, useful for unindexed repos.

The index is updated incrementally when you re-run zg index. Switching embedding models requires a full --rebuild because vector spaces from different models are not interchangeable even at the same dimensions. Indexed results carry a freshness state of fresh or possibly_stale, letting an agent act without running a separate status check first.

How it surfaces to AI coding agents

Running zg install detects Codex, Claude Code, Cursor, and OpenCode on the machine and wires up a local MCP (Model Context Protocol) integration automatically. The server communicates over Streamable HTTP on a loopback-only address, with optional bearer authentication.

The default agent toolset is deliberately small: just two tools. zvec_grep_search handles queries where intent is known but the exact string is not. zvec_grep_rg handles known symbols, paths, or regexes. Index lifecycle operations (create, drop, status) stay in the CLI and are only exposed to agents via an opt-in --mcp-toolset full flag. The documentation explicitly states that an agent must never silently create, rebuild, or delete a persistent index.

Output is shaped to save context window space. Results come back grouped by file with line spans. Source previews are omitted by default. Flags that would change the output format, such as --json, --count, -l, and --vimgrep, are rejected to keep the compact format consistent.

What embedding models are available?

The catalog covers ten local models and three remote Qwen endpoints. The default, local/potion-code-16m-v2, uses static vector lookup (Model2Vec), so a GPU adds no speed benefit. Heavier local options include jina-embeddings-v2-base-code, embeddinggemma-300m, and qwen3-embedding-0.6b. Remote options go up to qwen/qwen3.7-text-embedding with a 128,000-token input limit and a multimodal variant, qwen/qwen3-vl-embedding.

Remote access is gated by design. Adding a provider credential alone does not authorize data transfer. You need either --allow-remote for a single command or a signed workspace grant via zg auth grant, revocable with zg auth revoke.

What do the benchmark numbers actually show?

The Qwen team ran two paired A/B tests. Both held the agent, model, prompt, runtime, and task constraints fixed. The zg condition added only a prebuilt index, MCP tools, and usage guidance. Index build time was excluded from the results.

Benchmark	Sample size	Tool calls change	Input tokens change	Other metric
SWE-QA-Bench	20 questions	More than 50% reduction	Nearly 50% reduction	Judge score up 1.50 points
BrowseComp-Plus	80 questions	Down 43.52%	Down 37.56%	Accuracy 98.67% to 99.00%; agent time down 38.58%

These numbers come from the vendor’s own runs, not independent replication. Sample sizes of 20 and 80 are small. Take the percentages as directionally interesting, not as settled benchmarks.

Why it matters

AI coding agents, including those built on top of tools like Claude Code and Cursor, currently spend a disproportionate share of their token budget on codebase navigation. A tool that cuts tool calls by 40-50% in vendor tests translates directly into lower API costs and faster completions, two things any team running agents at scale cares about.

The restraint in the MCP design is worth noting. Keeping index management out of the agent’s default toolset prevents the class of bugs where an agent decides to rebuild or delete an index mid-task. That is a thoughtful default, not a limitation.

For teams exploring AI integration into their development workflows, zg fits into a broader picture of making agents cheaper and more predictable to operate. The Apache 2.0 license removes any friction around commercial deployment. The no-GPU default means you can test it on any developer machine today without provisioning anything extra.

Our take

The concept is sound. Ripgrep is fast for known strings, BM25 is good for keyword recall, and vector search covers the “what does this function do” queries that neither of the others handles well. Putting all three behind one interface with a sensible fallback order is genuinely useful, not just a packaging exercise.

The honest caveats: the benchmark samples are tiny and vendor-run, the benchmarks section in the repository is still a placeholder, and there is already a minor discrepancy between the eleven models cited in the launch post and the ten in the current docs. These are launch-day rough edges, but they matter if you are evaluating this for production use at scale.

For teams building workflow automation that includes AI coding agents, this is worth a weekend test. Index your main repo, wire it into Claude Code or Cursor, and measure actual tool call counts before and after. That is the only benchmark that matters for your specific codebase, and it costs nothing to run.

What to do about it

1. Install with npm install -g @zvec/zvec-grep (Node.js 22+ required).
2. Run zg index in your project root to build the initial index.
3. Run zg install to auto-detect and wire up your coding agent (Codex, Claude Code, Cursor, or OpenCode).
4. Use the default two-tool MCP setup before experimenting with --mcp-toolset full.
5. Compare token usage and tool call counts on a representative task before and after, and replicate the vendor’s numbers yourself.

If you want to cut AI agent costs, measure your tool calls first; zg is a practical starting point worth testing this week.

Source: Marktechpost