English | 中文

Know the words—or don’t. Just zg.

The local-first search layer for humans and agents.

🎬 Tour | 💫 Features | 🚀 Quickstart | 📚 Docs | 📊 Benchmarks | 🤝 Community

zg (zvec-grep) 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.

🎬 See it in action

Install the integration once, index the workspace, then search from the terminal or ask your agent naturally.

💫 Why zg?

• Works out of the box — one guided install connects zg to your agent on macOS, Linux, or Windows; ask naturally, with no search syntax to learn.
• All-in-one retrieval layer — semantic discovery, BM25-ranked retrieval, exact text, and regex search all stay behind zg.
• Agent- and human-friendly — compact, file-oriented context for agents and readable terminal output for people, with less noise for both.
• Local first, permission aware — ripgrep, indexes, and local models stay on your machine; remote embeddings require explicit authorization.

🚀 Quickstart

Requires Node.js 22 or newer on macOS, Linux, or Windows.

1. Install and connect your agent

npm install -g @zvec/zvec-grep
zg install

zg install detects Codex, Claude Code, Cursor, and OpenCode and configures the local MCP integration. See Agent integrations for managed configuration, permissions, and uninstall instructions. You can also select one explicitly:

zg install --target codex --yes

2. Index your repository

cd your-repository
zg index --embedding local/potion-code-16m-v2

This quickstart uses the lightweight Potion Code v2 model so you can build the first index quickly. The first run downloads it; the index stays in .zvec-grep/, and later updates only need zg index. See the retrieval pipeline to control scope, updates, and rebuilds.

3. Ask your agent

My app forgets dark mode every time I refresh. Find out why.

The agent uses zg for semantic discovery and ranked keyword retrieval, while exact lexical lookup stays with native grep or rg. The MCP guide describes the default search tool and the optional full toolset, which retains managed rg.

To search directly from the terminal, use the same local layer. See the CLI guide for routes, filters, and output controls.

zg query --human "theme preference persistence on startup" --limit 3

📊 Benchmarks

🚧 Work in progress.

🗺️ Roadmap

zg is moving toward richer multimodal formats, stronger hybrid retrieval, a more out-of-the-box experience, and support from desktop to mobile.

Explore the full Roadmap.

🤝 Join Our Community

💬 DingTalk	📱 WeChat	🎮 Discord	X (Twitter)
Scan to join	Scan to join	Click to join	Click to follow

❤️ Contributing

Community contributions are always welcome—bug fixes, features, and documentation improvements all help make zvec-grep better.

Check out our Contributing Guide to get started!