zvec-grep
The zg local-first search tool: ripgrep, BM25 and vector search unified behind one interface for humans and agents
Low risk
We rate an entry low when it mostly gives the agent instructions and reference material.
Why this level
- The tool indexes and reads project files locally and does not write to the project
Install
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/zvec-grepDetects the agents on your machine, checks the risk and pins the version.
Other ways to install
Install the tool
npm install -g @zvec/zvec-grepInstall with npm install -g @zvec/zvec-grep, then build the index in the project folder: zg index --embedding local/potion-retrieval-32m. Connect zg to your agent following docs/01-agents.md for the client you use, such as Claude Code or Cursor.
Other ways from the author
npm install -g @zvec/zvec-grepRequires Node.js 22 or newer.
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.
Security check
- The tool indexes and reads project files locally and does not write to the project
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.
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.
Related
A skills library that gives coding agents a development process: brainstorming, planning, TDD, subagents and code review
Skills for real engineers by Matt Pocock
Skills For Real Engineers
Small composable skills for engineering with agents: plan grilling, TDD, bug diagnosis, code review and architecture
GitHub toolkit for spec-driven development: the specify CLI adds agent commands and skills to a project, from principles to implementation
Reference MCP servers
Model Context Protocol servers
Official reference MCP servers: Filesystem, Fetch, Git, Memory, Sequential Thinking, Time and Everything