Developers using AI coding agents are all too familiar with the iterative loop of discovery. An agent attempts to locate a specific function or logic block, runs a grep command, fails to find the exact keyword, and then tries another variation. This trial-and-error process creates a massive token tax, bloating the context window with failed search results and redundant tool calls that slow down the development cycle. The friction lies in the gap between a developer's natural language intent and the rigid requirement of exact string matching in traditional local search tools.
The Architecture of Local-First Hybrid Search
To bridge this gap, the Qwen team has open-sourced zvec-grep, referred to as zg, a local-first search tool designed specifically to optimize how AI agents interact with codebases. The core innovation of zg is its hybrid approach, which merges the surgical precision of ripgrep (rg) with the semantic flexibility of vector search and BM25 ranking. By combining these methodologies, zg allows users and agents to navigate local code and documentation using natural language intentions, narrowing the search scope to the exact location of relevant information without requiring a known keyword.
Technical performance benchmarks demonstrate the efficiency of this on-device approach. In a test environment utilizing an Apple M4 Pro, zg indexed a total of 3,457 Django files in under 30 seconds. The entire pipeline—from file scanning and extraction to embedding and retrieval—runs locally. To ensure high speed and low hardware overhead, zg employs a 16M parameter embedding model, local/potion-code-16m-v2, which operates effectively without the need for a GPU. This design choice ensures that the tool remains accessible across various hardware configurations while maintaining the latency required for real-time agentic workflows.
Compatibility is a central pillar of the zg ecosystem. The tool supports CLI interfaces across macOS, Linux, and Windows and is fully compliant with the Model Context Protocol (MCP), the emerging standard for connecting AI models to external tools. zg is engineered to automatically detect and share local indexes with popular AI code editors, including Codex, Claude Code, Cursor, and OpenCode. This eliminates the need for developers to deploy and manage separate search services. Installation and configuration are streamlined through a simple two-step process:
npm install -g @zvec/zvec-grep
zg installSolving the Agentic Token Tax
While the speed of indexing is impressive, the true value of zg emerges when analyzing agent behavior during complex tasks. Traditional tools like ripgrep are indispensable when the exact keyword is known, but they fail when an agent must search for a conceptual implementation or a domain-specific pattern. This often forces the agent into a cycle of repetitive searching, which consumes significant input tokens and increases the likelihood of context overflow.
Data from the SWE-QA-Bench evaluation reveals a dramatic shift in efficiency when zg is integrated. The results show that both tool calls and input tokens were reduced by nearly half. Specifically, in the BrowseComp-Plus evaluation, the accuracy of the agent increased from 98.67% to 99.00%, while input tokens dropped by 37.56% and tool calls decreased by 43.52%. Furthermore, the overall execution time for the agent was reduced by 38.58%, and the Judge score saw an increase of 1.50 points.
This improvement stems from the way zg handles the search pipeline. Rather than forcing every query through a rigid sequence, zg utilizes a flexible routing mechanism. If the input provides sufficient clues for an exact match, the tool jumps directly to the precision search phase. If the query is vague or intent-based, it begins with semantic vector search to narrow the field before refining the results. By providing semantic discovery and relevance ranking alongside exact string matching, zg prevents the agent from wasting cycles on unsuccessful keyword guesses.
Currently, the tool is optimized for code and text files. The Qwen team has confirmed a roadmap to expand these capabilities to include PDF, Word, and PowerPoint documents, as well as the integration of Optical Character Recognition (OCR) and multimodal search. This evolution will transform zg from a code-search utility into a comprehensive local knowledge engine for AI agents.
The shift toward hybrid, local-first indexing suggests a future where AI agents no longer struggle to find the needle in the haystack, but instead possess a semantic map of the entire local environment.
