zg (zvec-grep): Local-First Search for Developers and AI Agents

What zg Is

zg (zvec-grep) is the Zvec team's answer to a real agent-workflow problem: retrieval rarely ends with one search. An agent starts from a task description, gradually discovers directions and keywords, then verifies with exact text. zg supports that loop by exposing three engines — ripgrep for exhaustive exact matching, BM25 for ranked lexical search, and zvec vector search for meaning — through one interface, with ranked, source-linked results designed to cut tool calls, tokens, and noise. It indexes code (C/C++, Go, Java, JS/TS, Python, Rust, plus Vue/Svelte scripts), Markdown/text/RST/HTML/XML, and CSV/JSON/TOML/YAML; PDFs, Office files, archives, executables, and media are skipped, and other code languages are treated as generic text until grammars exist.

Install and First Index

Requires Node.js 22+. npm install -g @zvec/zvec-grep, then zg index in any project. The default embedding model is local/potion-code-16m-v2 — a 16M-parameter static model, ~32 MiB cache, no GPU. The index lives in .zvec-grep/ under the project root, with incremental updates. The vendor's timing datapoint: Django's 3,457 files indexed in under 30 seconds on an M4 Pro — a single vendor measurement, not a reproducible benchmark.

The Five Retrieval Routes

The same routes work from the CLI (zg query "<description>", with --limit/--preview/--refresh/--debug/--trace controls and glob/type scoping) and from agents through MCP. Note one asymmetry: the CLI groups results per query group without cross-group filling from MCP.

Agent Integrations and MCP

zg install auto-discovers Codex, Claude Code, Cursor, and OpenCode (plus Qwen and Qoder) and configures managed MCP entries, guidance, and approvals for them — zg uninstall reverses it symmetrically. The MCP server is Streamable HTTP on http://127.0.0.1:7999/mcp, loopback-only. The default agent toolset exposes exactly one tool — zvec_grep_search (inputs: root, query/queries/fts/vector, fuse, limit ≤50, globs, fileTypes, symbolTypes, date filters, freshness) — while the full toolset adds managed ripgrep and index/status tools (six tools total). Execution modes are auto (default; does not start a missing server), server (shared daemon, background refresh, model reuse), and direct. Only zg query --rg needs neither index nor server.

The Local-First Privacy Model

Scan, extract, embed, index, and retrieve all run on-device by default. There are two separate authorization layers, and conflating them is the main privacy mistake to avoid: MCP tool approval governs what an agent can search; remote-embedding authorization (--allow-remote per command, or zg auth grant --capability embedding --scope workspace) governs whether any data ever leaves the machine — and it is never implied by MCP approval. The 11-model embedding catalog is local (Potion/ONNX/GGUF) plus one Qwen remote option; the Bearer token protects the local endpoint only.

Vendor Benchmarks, With Caveats

zg ships paired A/B benchmarks (agent decides when to use it; index time excluded; run-to-run variance disclosed; contamination risk flagged). BrowseComp-Plus (100 cases × 300 trials, Codex, qwen3.7 embedding): accuracy +0.33pp (98.67 → 99.00%) while input tokens fell 37.56%, tool calls fell 43.52%, and time fell 38.58%. SWE-QA-Bench (20 tasks, Claude Code with Opus 5): judge score +1.50 with tool calls and input tokens roughly cut in half. These are vendor-run results — treat the near-flat accuracy as the honest headline: the value claim is efficiency, not quality. Full protocols live in the benchmarks READMEs.

What zg Does Not Do (Yet)

The roadmap is explicit about non-goals today: graph search, query rewriting, model reranking, native PDF/Office support, and image/multimodal retrieval are all planned, not shipped. Mobile (iOS/Android) is roadmap. Platforms today: macOS, Linux, Windows (CLI + MCP).

Common Failure Modes

1. Agent returns stale results after edits — the index refreshes via the server mode's background watcher; in direct/auto modes pass --refresh or set freshness filters. Verify with zg status.
2. Semantic route misses exact symbols — expected: indexed routes are ranked samples. Follow semantic hits with --rg for exhaustive verification, exactly the pipeline the docs recommend.
3. MCP tool not appearing in your agent — zg install only auto-discovers supported clients; for others, point the client at http://127.0.0.1:7999/mcp manually and confirm the agent toolset (one tool) vs full (six).
4. Binary/PDF files missing from results — by design: archives, executables, PDFs, and Office formats are skipped; only code, text, and structured-data formats are indexed today.

Use It If

Use zg if your agent loop burns tokens re-searching large local codebases or docs — the efficiency deltas and one-tool MCP surface are directly useful, and local-only defaults keep private repos safe. Skip if you need exhaustive semantic recall (indexed routes are ranked samples; only --rg is exhaustive, and it is lexical), PDF/Office indexing, or multimodal search. The open question — vendor-run benchmarks, no independent replication yet — is answered by the paired A/B protocol: run it on your own repo.

FAQ

Does zg replace ripgrep?

It includes ripgrep. Exact-match search still routes through a managed rg — the value is ranked semantic/hybrid discovery above it, with verification via exact text when needed.

Does my code leave my machine?

Not unless you explicitly grant remote-embedding authorization. Indexing, embedding (default local model), and retrieval are on-device; MCP approval never implies remote transfer.

Which agents does zg install into?

One command configures Codex, Claude Code, Cursor, OpenCode, Qwen, and Qoder; the default MCP toolset exposes a single search tool so agents adopt it without prompt-specific instructions.

What does it cost?

Nothing — Apache-2.0, local models included. The only billable path is the optional remote embedding model.

Sources

• GitHub — zvec-ai/zvec-grep (README, docs, benchmarks)
• Zvec — From rg to zg: Local Search Beyond Keywords (launch post)
• zg docs — Agent integrations (install targets, MCP surface)
• zg docs — Benchmarks index (A/B protocols)
• GitHub — alibaba/zvec (underlying engine)