Repolode
Submit
zvec-ai

zvec-ai/zvec-grep

Local-first search CLI and agent tool that combines ripgrep, BM25 and vector search over your workspace.

View on GitHub
Stars
4,290
Forks
262
Open issues
90
Last commit
yesterday

What is it?

zg (zvec-grep) is a local search tool that runs over a workspace's files. It combines exact text and regex matching from ripgrep, keyword ranking with BM25, and semantic vector search, so a query can find passages by meaning and then be verified with exact text when needed. It is built on the zvec vector database and is available as a Node.js package, with the README describing the TypeScript/Node.js implementation and a separate Rust implementation in the repository.

The same index can be used from the terminal through the zg CLI or by an AI agent. The project lists integrations with agents such as Codex, Claude Code, Cursor, GitHub Copilot, VS Code and OpenCode, and includes an MCP guide. It indexes source code, documents and structured data while keeping source locations, and runs on macOS, Linux and Windows. Files, indexes and local embedding models stay on the local machine, and remote embedding providers receive data only when enabled.

The project supports local embedding models, including Potion/model2vec and llama.cpp and Transformers.js runtimes, and provides options for indexing concurrency and GPU memory limits. Index data is stored in a .zvec-grep/ directory under the indexed root.

Key features

  • 01Combines ripgrep exact and regex search with BM25 keyword ranking and vector semantic search.
  • 02Works from the terminal via the zg CLI or from AI agents through MCP-style integrations.
  • 03Indexes source code, documents and structured data while keeping source locations.
  • 04Runs on macOS, Linux and Windows, requiring Node.js 22 or newer for the npm package.
  • 05Keeps files, indexes and local models on your machine by default.

Use cases

  • Finding code paths and architecture details across a large repository when the exact symbol name is unknown.
  • Letting an AI coding agent search a local project with ranked, source-linked results.
  • Searching a folder of mixed documents and code by meaning instead of exact keywords.
  • Running private semantic search without sending files to a remote service.

Quick start

  1. 1

    Install the zg CLI from npm (requires Node.js 22 or newer)

    npm install -g @zvec/zvec-grep
  2. 2

    Index your workspace with a local embedding model

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

    Run a search from the terminal

    zg query --human "An unseen creature left a few marks. What did the detective infer?" --limit 3

Things to know

  • Requires Node.js 22 or newer.
  • The agent example depends on OpenCode and on free model availability, which can change.

In collections

Open-source AI agent frameworks & appsMCP serversCLI & terminal toolsPrivacy & local-first tools

Topics

#code-search#semantic-search#full-text-search#vector-search#local-first#cli#ai-agents#mcp#bm25#ripgrep

FAQ

What is zvec-grep?
Local-first search CLI and agent tool that combines ripgrep, BM25 and vector search over your workspace. zg (zvec-grep) is a local search tool that runs over a workspace's files. It combines exact text and regex matching from ripgrep, keyword ranking with BM25, and semantic vector search, so a query can find passages by meaning and then be verified with exact text when needed. It is built on the zvec vector database and is available as a Node.js package, with the README describing the TypeScript/Node.js implementation and a separate Rust implementation in the repository.
Is zvec-grep free to use? What license does it have?
zvec-grep is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is zvec-grep still maintained?
Actively maintained. The last commit to zvec-grep was on Nov 6, 2026.
What can I use zvec-grep for?
Finding code paths and architecture details across a large repository when the exact symbol name is unknown. Letting an AI coding agent search a local project with ranked, source-linked results. Searching a folder of mixed documents and code by meaning instead of exact keywords. Running private semantic search without sending files to a remote service.
How do I install zvec-grep?
Install the zg CLI from npm (requires Node.js 22 or newer): npm install -g @zvec/zvec-grep Index your workspace with a local embedding model: zg index --embedding local/potion-retrieval-32m Run a search from the terminal: zg query --human "An unseen creature left a few marks. What did the detective infer?" --limit 3
Where can I get zvec-grep?
The source code and installation instructions are on GitHub: https://github.com/zvec-ai/zvec-grep

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects