ZG: Qwen's Semantic Grep Tool for AI Coding Agents, Explained
Qwen open-sourced ZG, a local semantic search tool blending ripgrep, BM25, and vector search. Here's how it works and how to install it.
What is ZG and why does it exist?
ZG (short for Z vector grep) is a local-first search tool open-sourced by Team Qwen that combines three search methods behind a single command-line interface: ripgrep for exact string matches, BM25 for keyword ranking, and vector embeddings for semantic meaning. The point is to close a gap that every developer and every coding agent runs into: you know what a piece of code does, but you don’t know what it’s called.
Standard grep and ripgrep are exact-match tools. They’re excellent when you know the literal string you’re looking for, and useless the moment you don’t. If you search for “restore theme preference” but the function is actually named hydrate_preferences, ripgrep returns nothing, because the code and your mental model of the code don’t share a keyword. A human deals with this by guessing synonyms and reading through files by hand. An AI agent deals with it by burning tool calls and tokens running the same blind guesses, which costs money and slows everything down.
ZG’s fix is to let you describe the intent of the code in plain English and have the tool rank results by semantic relevance, even when there’s zero literal overlap between your query and the source text.
TL;DR
- ZG merges three search engines (ripgrep, BM25, and vector search) into one interface so queries can match either exact strings or the meaning behind them.
- It’s built for AI agents as much as humans, since agents waste tool calls and tokens when a keyword search comes up empty on a semantically relevant match.
- Installation is a single global npm install and requires Node.js as the only prerequisite.
- Indexing runs locally with an on-device embedding model, so no code or text leaves the machine, and it builds a searchable index stored in a project-local folder.
- A test against Alice in Wonderland and Sherlock Holmes showed ZG correctly surfacing Sherlock Holmes passages about footprints and tracks from a query that never used those words.
- Benchmark figures shared by Qwen’s repo report tool-call reductions as high as 82.7% fewer input tokens and 83.5% fewer tool calls on some real repositories, with answer quality holding steady or improving rather than degrading.
- On a real-world test against the Django codebase, plain ripgrep returned nothing for an intent-based query, while ZG correctly located the relevant code block.
Plans first. Then code.
Remy writes the spec, manages the build, and ships the app.
How does ZG actually work?
ZG sits in front of three retrieval methods and picks results using ranking signals from all of them:
- Ripgrep handles exact, literal matches, the same fast text search developers already rely on.
- BM25 provides keyword-based ranking, which is useful when queries share some but not all vocabulary with the target text.
- Vector search encodes both the query and the codebase into embeddings, then finds passages that are semantically close even when there’s no shared vocabulary at all.
The workflow starts with indexing. ZG scans a directory, breaks files into searchable chunks (referred to as “entities” or symbols), and builds a local index using an on-device embedding model. Nothing gets sent to an external server during this step. In one demonstration, a folder containing two full books (roughly 433 searchable entities) indexed in under five seconds. A much larger test against the Django codebase, around 3,500 files, produced roughly 47,000 searchable code symbols, and indexing still completed quickly.
Once indexed, a query returns results that show which method contributed to the match: full-text search, vector similarity, or both. This transparency matters if you’re deciding how much to trust a given hit or whether you need to double-check ranking order for your own use case.
How do you install and run ZG?
The setup shown in the walkthrough was straightforward on Ubuntu:
- Install Node.js if it isn’t already on the machine. This is the only prerequisite.
- Install ZG globally via npm. The install is lightweight and finishes quickly.
- Verify the install with a simple version-check command.
- Point ZG at a target folder and run the indexing command, which downloads a ranking/embedding model on first use and then builds the local index.
- Query the index using plain-English descriptions of what you’re looking for, rather than exact keywords.
The index itself lives in a local hidden folder alongside the project (referred to in the demo as a .zvec style directory), which stores the processed, searchable version of the content without needing a database server or cloud account.
What do the benchmark numbers actually show?
Qwen’s own repository includes benchmark comparisons across two types of tasks, and the reported gains are the main argument for adopting ZG in an agent pipeline rather than relying on grep alone.
On coding tasks measured with a benchmark called SWE-QA-bench, ZG reportedly cut tool calls by 58.6% and input tokens by 47.3%, while answer quality went up rather than staying flat. On a general text retrieval benchmark called BrowseComp-Plus, ZG held answer accuracy at 99% while cutting agent completion time by roughly 38.6%.
When tested against specific real-world repositories such as pylint and matplotlib, the savings were larger still: up to 82.7% fewer input tokens and 83.5% fewer tool calls on pylint specifically. Across every repository tested, answer quality didn’t just hold steady, it improved. That combination (lower cost, less latency, better answers) is the core pitch: agents spend less time and fewer tokens searching, and they still get better results than plain grep would give them.
Is ZG worth using over plain ripgrep or grep?
It depends on what you’re searching for. If you already know the exact function name, variable, or string you need, ripgrep alone is still faster and simpler; there’s no reason to add a semantic layer to a search you can already nail with exact matching.
Where ZG earns its place is the far more common scenario: you know what the code does but not what it’s called. That’s the situation that burns human time and agent tokens alike. In one demonstration against the Django codebase, a plain ripgrep search using intent-based phrasing returned nothing, because the literal words didn’t appear anywhere in the code. The same query run through ZG found the relevant block, because the vector search layer matched on meaning rather than spelling.
For teams building retrieval-augmented generation (RAG) pipelines or coding agents that need to search a codebase autonomously, this matters more than it does for a human occasionally grepping a repo. Every failed exact-match search an agent runs is a wasted tool call and a chunk of burned tokens, and those costs compound across a long agent session. Cutting tool calls and tokens by even a third, as the benchmark figures suggest, adds up quickly at scale.
The one caveat worth flagging: ranking order isn’t guaranteed to be perfect out of the box. It’s reasonable to spot-check how ZG orders results for your specific codebase or document set before trusting it blindly in a production pipeline, though this doesn’t appear to be a fundamental limitation, just a tuning step.
Frequently Asked Questions
What does ZG stand for?
ZG stands for Z vector grep. It’s named as an extension of the grep and ripgrep family of command-line search tools, but with vector-based semantic search added on top.
Does ZG require an internet connection or cloud account?
No. Indexing and embedding generation run locally using an on-device model. Once the initial model download completes, searches and indexing happen on the machine without sending code or text externally.
What’s the only prerequisite to install ZG?
Node.js. The tool installs globally via npm and is described as lightweight, with the install itself completing in a short amount of time.
Can ZG replace ripgrep entirely?
Not necessarily. Ripgrep is still the better choice when you know the exact string you’re searching for. ZG adds value specifically when your query and the target code don’t share vocabulary, which is where pure exact-match tools fail.
Why does this matter more for AI agents than for human developers?
Because agents pay for every failed search in tool calls and tokens, and those costs scale with the length and complexity of an agent session. Benchmark figures shared in Qwen’s repository show reductions in tool calls and input tokens of well over 50% on some real repositories when using ZG instead of relying purely on exact-match search.