Coding agents waste a large part of their tool budget on search. When they need a known symbol they can rely on exact tools like ripgrep, but when the request is described in plain language they often guess keywords, read whole files, and stitch context manually. Each detour adds extra tool calls, consumes tokens, and increases wall‑clock time.
zg (zvec‑grep) is an open source local‑first search layer that puts semantic search, BM25 ranking, and ripgrep behind a single interface for both humans and agents. It installs from npm, works on Node.js 22 or newer on macOS, Linux, or Windows, needs no GPU with the default model, and is released under Apache 2.0 so commercial use is allowed.
The tool indexes a workspace once and then offers four ways to query it. A hybrid default combines intent with lexical anchors, a pure BM25 route returns exact term matches, a vector route gives conceptual similarity, and a ripgrep route does exhaustive literal or regex matching without needing an index. Results are grouped by file with line spans, and previews are omitted by default to keep the agent context small.
When installed, zg detects agents such as Codex, Claude Code, Cursor, and OpenCode and wires a local MCP integration that exposes two tools by default: one for semantic‑style search when the exact string is unknown, and one for ripgrep‑style search when a symbol, path, or regex is known. Index creation, updates, and deletion stay under the CLI; agents must never silently modify the persistent index.
Embeddings run on device by default using a lightweight static model; heavier local or remote models are available but remote use requires explicit permission per command or via a workspace grant.
In vendor A/B tests on small benchmarks, zg cut tool calls by roughly half and input tokens by nearly half while improving answer quality. Indexing a medium sized repository finishes in under thirty seconds on a typical laptop.
#AI #Product #DevTools #CodeSearch #Agentic #OpenSource