Published: 2026-09-09
Deep dive

Semantic grep cut agent tool calls 58% and input tokens 47% in the project's own benchmarks

Chapters / key moments (click to jump — plays here on the page)

The problem is one every agent hits and most people pay for without noticing. You know the code restores a theme preference on startup; the function is called hydratePreferences. Your query and the code share no keyword, so grep returns nothing and you start guessing synonyms. Hand that to an agent and it burns tool calls and tokens doing the same blind guessing. ZG puts exact matching, keyword ranking and meaning-based search behind a single interface, runs entirely on-device, and the project's published numbers for what that saves an agent are the reason to care.

Source video

"Qwen Gifts ZG: Local-First Semantic grep for You and Your AI Agent" by Fahd Mirza — Watch on YouTube →

Step-by-Step Breakdown

Understand what it actually combines
Three search strategies behind one interface: ripgrep for exact matches, BM25 for keyword ranking, and vector search for meaning. The pitch is that ripgrep is brilliant when you know the exact string and useless when you only know the intent — ZG covers both without you choosing up front.
Verify it is genuinely local
Indexing downloads a ranking model and runs an on-device embedding model; the index is written to a local folder. The demo shows the index directory on disk. For anyone indexing a private codebase, this is the property that decides whether the tool is usable at all.
Test it the honest way — no shared keywords
The demo indexes two unrelated books and then asks a plain-English question sharing almost no words with the text. All three top hits come from the correct book, matched by combined full-text and vector scoring, landing on a scene the query never named directly.
Then test it on real production code
A cloned Django repository, ~3,500 files indexed into ~47,000 symbols. Plain grep for the intent returns nothing; ZG returns the relevant block. That is the case the tool exists for.

Commands & Code Shown

`npm install -g @qwen/zg`

npm install -g @qwen/zg

Purpose: Installs ZG globally. Node is the only prerequisite and the package is lightweight.

When to use: Once per machine. Verify the exact package name against the project's repository before running — the video installs from npm but the package name is not clearly legible on screen.

`zg --version`

zg --version

Purpose: Confirms the install succeeded and ZG is on your PATH.

When to use: Immediately after installing, before wiring it into anything.

`zg index .`

zg index .

Purpose: Builds a local index of the current folder using an on-device embedding model. Nothing leaves the machine. The index is stored in a local dot-directory beside the content.

When to use: Once per codebase, and again after substantial changes. In the demo it scanned two full books into 433 searchable entities in under five seconds, and a cloned Django tree of ~3,500 files into ~47,000 code symbols.

`zg "<plain English description of what the code does>"`

zg "<plain English description of what the code does>"

Purpose: Searches by intent rather than by literal string, combining ripgrep exact matches, BM25 keyword ranking and vector similarity, and ranking results by relevance.

When to use: Whenever you know the behaviour but not the name. In the Django test, plain grep for the same intent returned nothing and ZG returned the relevant block.

Published savings (from the project's own repository)

Benchmark	Tool calls	Input tokens	Answer quality
SWE-QA-bench (coding tasks)	−58.6%	−47.3%	Went up
BrowseComp+ (general retrieval)	Agent time −38.6%	—	Held at 99%
pylint repository specifically	−83.5%	−82.7%	Went up

These are the project's own published figures, not an independent evaluation, and the reviewer presents them as such — they come from charts in the repository. The direction is consistent across every repo shown and the quality bars move up rather than down, which is the part that would be hardest to fake convincingly; treat the magnitudes as vendor numbers until someone reproduces them.

Gotchas & Caveats

All performance figures are the project's own. No independent reproduction is offered and none is claimed.
The npm package name is not clearly legible in the demo — check the project repository before installing anything by that name.
Node.js is required. The index lives beside your content in a dot-directory, which you will want in your ignore files.
The reviewer promotes a newsletter and channel membership; the tool itself is free and open source, and no sponsorship is stated.

Key Takeaways

The saving comes from not guessing. An agent that finds the right code on the first search does not spend twenty tool calls broadening a keyword search — which is why the tool-call reduction is larger than the token reduction.
Local-first is the enabling property. On-device embeddings mean you can index a private repository without shipping it anywhere.
Open-sourced internal tooling. The framing worth noting: this is a model lab open-sourcing the tools it uses internally, not just weights.
Indexing is fast enough not to be a barrier — seconds for small corpora, and a full Django tree handled in the demo.
Answer quality rose on every repository shown, which is the unusual part. Most token-reduction techniques trade quality for cost.
One honest caveat from the reviewer: result ordering may need checking if you embed this in your own RAG pipeline, though he does not consider it a dealbreaker.