zg Wants to Be the Last Search Tool You Install

You've got ripgrep for fast text matching, some vector database for semantic search, and maybe a BM25 implementation duct-taped in between. Each one has its own index, its own query syntax, and its own way of making you feel like you're doing three jobs instead of one. zg is a local-first search layer that puts ripgrep, BM25, and vector search behind a single interface, so you can search by keyword, by meaning, or by regex without juggling separate tools.

What It Does

zg (short for zvec-grep) is a search tool built on top of zvec. It unifies three search modes—ripgrep-style exact text and regex matching, BM25 relevance ranking, and vector search for semantic discovery—into one interface you can use from the terminal or hand off to an agent. The idea is that you index a workspace once, then query it however you need: exact matches when you know the words, ranked results when you don't, and semantic search when you're fishing for concepts rather than strings.

It's written in TypeScript and runs on Node.js 22 or newer. There's also a separate Rust implementation developed independently in the rust/ directory. The project supports macOS, Linux, and Windows, and it's designed to work the same way whether you're typing commands yourself or letting an agent call it on your behalf. It handles source code, documents, and structured data, preserving source locations so results point back to the actual files and lines they came from.

Why It's Cool

It solves the "which tool do I reach for" problem. Most developers have a mental decision tree: ripgrep for known strings, something else for fuzzy matching, maybe a vector store if they've set one up. zg collapses that tree into one command. You don't have to know in advance whether you want exact or semantic search—you can start with one and escalate to another without switching contexts.

The agent angle is genuinely practical. The README emphasizes "fewer tool calls, fewer tokens, less noise." That's not just marketing—it's a real constraint when you're working with agents that have context windows and API costs. A single search interface that returns ranked, source-linked results means your agent spends less time querying and more time doing whatever you actually asked it to do. The install-once-index-once workflow applies equally to you and your agent, which is a cleaner mental model than maintaining separate search setups for each.

Local by default is the right call. Files, indexes, and local models stay on your machine. Remote embeddings only receive data if you explicitly permit it. For anyone working with sensitive code or documents, that's a meaningful default—not an afterthought bolted on for compliance.

Multi-format support without losing structure. Searching source code is different from searching prose, which is different from searching structured data. zg preserves useful structure and source locations across all three, so a result tells you not just what matched but where it lives. That's the difference between a search tool you use once and one you keep in your workflow.

It meets you where you are. Terminal user? There's a CLI. Agent-driven workflow? There's an integration. The README's setup example walks through installing the agent integration, indexing a workspace, and letting the agent search it. Same workspace, same index, two access patterns.

How to Try It

1. Make sure you have Node.js 22 or newer installed.

2. Install zg globally:

npm install -g @zvec/zvec-grep

1. Set up a sample workspace to test it against. The README suggests a small "bookshelf" of text files:

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

1. Index the workspace and start searching. The README's tour shows installing the agent integration, indexing a workspace, and letting an agent search it—but you can also drive it directly from the terminal.

For the full walkthrough, architecture details, and documentation, head to the repository: github.com/zvec-ai/zvec-grep. The docs live in the docs/ directory, and there's a separate README for the Rust implementation if that's more your speed.

Final Thoughts

zg is aimed at developers who are tired of maintaining separate search setups for text, relevance, and semantics—and at anyone building agent workflows where search efficiency directly affects cost and latency. It's not trying to replace your entire toolchain; it's trying to be the one search layer you reach for first, whether you know the words or you don't. The local-first design and multi-language support make it a reasonable default for teams that care about where their data goes. If you've been meaning to clean up your search stack, this is a solid place to start.

Follow @githubprojects for more developer tools and open source projects.