zvec-grep CLI
The zg local-first search tool: ripgrep, BM25 and vector search unified behind one interface for humans and agents
- 4,308 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- Runs a local CLI and MCP server that indexes project files into the .zvec-grep folder
- With a remote embedding model it sends file fragments to that provider
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/zvec-grepDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Runs a local CLI and MCP server that indexes project files into the .zvec-grep folder
- With a remote embedding model it sends file fragments to that provider
This is third-party code. Review the repository files before installing.
What it does
zvec-grep, via the zg command, unifies exact regex search like ripgrep, full-text BM25 search and semantic vector search behind one local index. The index is built once over a project folder and stored in a hidden .zvec-grep directory. The tool searches source code, documents and structured data while keeping a link back to the original location. It runs as an ordinary terminal command or as a server an agent connects to over MCP, returning source-linked results so the agent needs fewer repeated calls and less context to explain.
Who it is for. For developers and coding agents that need one search combining meaning and exact text across a large workspace.
Good fit when
- The agent needs to find relevant code or documents by meaning, not only by keyword
- You need one index usable both from the terminal and from an agent
- Reducing the number of search tool calls and the returned context matters
Not a fit when
- Plain grep or ripgrep without semantic search is already enough
- You do not want to maintain a local index and an embedding model
Example request
Find where the project handles the auth error, by meaning rather than exact textLimitations
Requires Node.js 22 or newer. Before searching you need to build an index with zg index and choose an embedding model, local or remote, for semantic search. With remote embeddings, data is sent to the provider only with explicit permission.
How to disable. Remove the package with npm uninstall -g @zvec/zvec-grep and delete the .zvec-grep index folder in each project where it was built.
FAQ
Do I need a cloud key for embeddings?
No, you can choose a local embedding model, such as potion-retrieval-32m, and everything stays on the machine.
How does zg differ from plain ripgrep?
zg adds BM25 full-text search and semantic vector search on top of familiar exact search, unifying them in one local index.
Discussion
No questions or reviews yet.
Related
CLI toolsJevGrep finds code from a description of what it does and returns lines with paths, as a CLI and as an agent MCP server.
codesearch searches code across several repositories with hybrid retrieval and runs fully offline, without a GPU or Docker.
Source search ranks matches using code structure and gives agents relevant snippets without a separate search index.
Jevgrep
jevgrep
A CLI for coding agents: finds code by a task description rather than by a string. A key from one of the model providers is needed
A local code search in Rust for agents: BM25, vectors and reranking, 65 languages, offline, with a skill and MCP server.
Local search and MCP server for agents: one Rust binary that indexes code, docs and logs
README in short
The README describes zvec-grep as a local-first search layer for humans and agents built on the zvec engine: ripgrep, BM25 and vector search unified in one CLI and MCP server. It documents integrations with Codex, Claude Code, Qwen Code, Qoder, Cursor, GitHub Copilot, VS Code and OpenCode. The main README covers the TypeScript implementation; a separate Rust implementation is developed in the rust folder. Apache 2.0 licensed.