CLI tool
zvec-ai/zvec-grep avatar
zvec-ai/zvec-grep

zvec-grep is three search engines behind one local-first index and one CLI

Local-first search across your workspace, built for humans and AI agents.

4,322 stars267 forksTypeScriptApache-2.0

At a glance

What is it?
zvec-ai/zvec-grep puts literal pattern search, ranked keyword search and vector search behind a single command called zg, over an index stored in a dot-directory in the project it indexes. The interesting part is the boundary it states plainly: which embeddings leave the machine.
Who is it for?
zvec-grep suits someone whose questions are about what a codebase or document set means rather than what it contains, and who wants the same index usable by a person and by an agent. It does not suit someone who needs a remote index.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • zvec-ai/zvec-grep4,322 ★ · +964
Star history
Repository2026-09-102026-11-15
zvec-ai/zvec-grep3.4k4.3k

964 Stars in the last 66 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Three search engines and one verb

The pitch is a unification, and the name explains the scope: the tool combines a literal pattern search, a ranked keyword search, and a vector search behind one local-first interface, so a query can be answered by exact text when that is right and by meaning when it is not. The readme describes the intended order of operations: discover by meaning, rank by relevance, then verify with exact text or a pattern when needed. The command is zg, short for zvec-grep. Files, indexes and local models stay on your machine by default, and the index itself is written into a dot-directory under the project root, which is the single most consequential design decision in the project.

The index lives in the project, which makes it shareable

The documentation states plainly that the index is stored in a dot-directory under the indexed project root. The claimed payoff for that arrangement is less searching and less context, since ranked results with source links are meant to replace a chain of individual lookups. The setup example makes the shape concrete: install the command globally, create a directory, fetch two public-domain texts into it, and index that directory with a named local embedding model.

bash
npm install -g @zvec/zvec-grep

The package manifest sets the runtime floor at Node 22 or newer.

Local models by default, remote only with permission

The privacy claim is specific enough to check. Files, indexes and local models stay on your machine, and remote embeddings receive data only with your permission. That phrasing matters because the index command takes an embedding choice as an argument, so choosing a local model is a decision you make at index time rather than a separate privacy setting. The example uses a named local model, and the readme is explicit that the same index is then queryable from the command line or by an agent on three desktop platforms.

Two front ends, one index

The try-it-yourself section deliberately shows the same question answered twice. First through an agent, after a single install command for that agent's configuration format, and the note is that the agent chooses the search tool on its own without the prompt naming it. Then directly from a terminal with a flag that selects the human output mode and a result limit. Both return passages from the same file ranked ahead of the other document, which is the point of the demonstration: the index does not change, only the caller does. The example query is a riddle about a detective and an unseen animal, which is a reasonable demonstration that meaning-based retrieval finds evidence exact matching would miss.

Failures are recorded per file, not per run

Indexing concurrency is capped differently per backend

Automatic limits depend on free video memory

Editorial conclusion

zvec-grep suits someone whose questions are about what a codebase or document set means rather than what it contains, and who wants the same index usable by a person and by an agent. It does not suit someone who needs a remote index. Before adopting it, check the Node version floor and decide whether you want a local embedding model at all.

Frequently asked questions

What is Zvec?

The readme names the engine this tool is built on and links to its own repository. What it describes for this project is the layer above it: a local-first search tool that combines literal pattern search, ranked keyword search and vector search behind one command, with the index written into a dot-directory under the project root.

What is better than grep?

The repository does not claim to replace it. The stated order is to discover by meaning and rank by relevance first, then verify with exact text or a pattern when that is what the question needs, with the example query being a riddle that exact matching would not answer.

What is the difference between grep and RAG?

The readme does not draw that comparison. It describes three search mechanisms combined behind one interface, and it claims the benefit in terms of context: ranked results with source links that surface the right evidence with fewer tool calls and fewer tokens than looking things up one at a time.

Official sources

  1. Issues
  2. License: Apache-2.0
  3. README
  4. Releases
  5. zvec-ai/zvec-grep on GitHub

Was this useful?