zvec-grep

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

What is zvec-grep?

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

Overview of zvec-grep

What it is

zg (zvec-grep) is a local-first search tool that unifies ripgrep, BM25, and vector search behind a single interface. It is designed for both human users and AI agents, allowing searches directly from the terminal or through agent workflows. The tool indexes files and stores indexes locally in a .zvec-grep/ directory under the project root.

Key features

  • Unifies three search methods: ripgrep (regex), BM25 (lexical ranking), and vector search (semantic similarity).
  • Supports multi-format search across source code, documents, and structured data while preserving structure and source locations.
  • Provides ranked, source-linked results to reduce tool calls and token usage.
  • Local by default: files, indexes, and local models stay on the user's machine; remote embeddings only receive data with explicit permission.
  • Works on macOS, Linux, and Windows.

Use cases

  • Searching codebases for architectural patterns, data flow, or call chains when the target location is unknown.
  • Searching documents (e.g., books, reports) by meaning or by exact text.
  • Agent-assisted search: agents can use zg automatically to retrieve evidence and answer questions, as demonstrated with OpenCode.
  • Cross-domain retrieval: the same tool works for code (symbols, signatures) and prose (sections, chunks).

Getting started

Install zg globally via npm: bash npm install -g @zvec/zvec-grep --allow-scripts=@zvec/zvec-grep Create a project directory, download sample files, and build an index: bash 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 After indexing, search directly: bash zg --preview detail 'An unseen creature left a few marks. What did the detective infer?' --limit 3 For agent usage, see the repository README for OpenCode configuration.

License and pricing

The project is licensed under Apache-2.0 and is open source.

Based on the project's public README and repository metadata.

Add this badge to your README

Featured on YunoDB Badge styles & help

Maintain this project? Show that it is featured on YunoDB.

Markdown[![Featured on YunoDB](https://yunodb.com/badge/zvec-aizvec-grep.svg)](https://yunodb.com/tools/zvec-aizvec-grep?utm_source=github&utm_medium=badge)
HTML<a href="https://yunodb.com/tools/zvec-aizvec-grep?utm_source=github&utm_medium=badge"><img src="https://yunodb.com/badge/zvec-aizvec-grep.svg" alt="Featured on YunoDB" height="20"></a>