Zvec Grep

English | 中文

Know the words—or don’t. Just zg. The local-first search layer for humans and agents.

🎬 <strong>Tour</strong> |
💫 <strong>Features</strong> |
🚀 <strong>Try it yourself</strong> |
📚 <strong>Docs</strong> |
📊 <strong>Benchmarks</strong> |
🤝 <strong>Community</strong>

zg (zvec-grep), powered by zvec, unifies ripgrep, BM25, and vector search behind one local-first interface. Use it directly from the terminal, or let your agent use it for you.

This README and the documentation describe the TypeScript / Node.js implementation. The Rust implementation is developed separately in rust/.

🎬 See it in action

💫 Why zg?

• Ready for humans and agents — install once, index once, then use the same workspace from the CLI or your agent on macOS, Linux, and Windows.
• Search beyond keywords — discover by meaning, rank by relevance, then verify with exact text or regex when needed.
• Multi-format search — search source code, documents, and structured data while preserving useful structure and source locations.
• Less searching, less context — ranked, source-linked results surface the right evidence with fewer tool calls, fewer tokens, and less noise.
• Local by default — files, indexes, and local models stay on your machine; remote embeddings receive data only with your permission.

🚀 Try it yourself

1. Set up a sample bookshelf

# Requires Node.js 22 or newer.
npm install -g @zvec/zvec-grep

mkdir zg-mystery && cd zg-mystery
curl --retry 3 --retry-all-errors --progress-bar -fL \
  -o alice-in-wonderland.txt https://raw.githubusercontent.com/GITenberg/Alice-s-Adventures-in-Wonderland_11/master/11.txt \
  -o sherlock-holmes.txt https://raw.githubusercontent.com/GITenberg/The-Memoirs-of-Sherlock-Holmes_834/master/834.txt

zg index --embedding local/potion-retrieval-32m

[!NOTE] The index is stored in .zvec-grep/ under the indexed project root.

[!TIP] If zg index or zg query fails, rerun the same command with --debug for diagnostics (supported in both direct and server modes). zg status --mode direct --debug reports per-file failures stored in an existing index; rerun a failed direct command to diagnose command-level fatal errors. Use zg status --mode server --debug to inspect recorded server indexing errors. For server connection failures, check zg server status and the server logs.

2. Choose how to search

For agents: ask with OpenCode

With OpenCode configured:

zg install --target opencode --yes
opencode models
opencode run --model opencode/nemotron-3-ultra-free \
  "An unseen creature left a few marks. What did the detective infer? Cite local evidence."

Free model availability can change. Check opencode models and replace the example model with one that is currently available in your environment.

OpenCode chooses zg on its own—the prompt does not name a tool.

See the full agent run and answer