Repository: zvec‑grep Clone URL: git clone https://github.com/moses-y/zvec-grep
1. Overview
zvec‑grep is a local‑first search engine that unifies keyword (ripgrep), BM25, and vector search behind a single CLI (zg) and an agent‑friendly API. The codebase is a fork of zvec-ai/zvec-grep (4349 stars) and contains 1 165 files across Rust, TypeScript, and Python. The primary goal is to let humans or LLM agents search a workspace with meaning‑aware results, keeping all data on‑premises unless the user grants remote embedding access.
2. Tech Stack
| Layer | Files | Tooling | Notes |
|---|---|---|---|
| CLI & Agents | src/ (136 TS files) | npm, TypeScript | zg is installed globally via npm install -g @zvec/zvec-grep. |
| Rust Engine | rust/ (601 Rust files) | Cargo | Performance‑critical components (e.g., indexing, query execution). |
| Benchmarks | benchmarks/ | Python + Rust | Two suites: browse‑comp‑plus and swe‑qa‑bench. |
| Python Utilities | benchmarks/.../datasets/.../Dockerfile | Docker | Each dataset ships a container that builds environment and runs tests. |
| CI | .github/workflows/* | GitHub Actions | ci.yml, rust-ci.yml, security.yml, dependency‑health.yml, benchmark‑* workflows. |
3. Entry Points
- CLI –
zg(installed via npm). The underlying script issrc/cli.ts. - Benchmarks –
- Browse suite:
benchmarks/browse-comp-plus/zg_bench/cli.py - SWE QA suite:
benchmarks/swe-qa-bench/zg_bench/cli.py - Rust‑bench entry:
rust/benchmarks/browse-comp-plus/zg_bench/cli.py
These scripts orchestrate dataset loading, indexing, query execution, and report generation.
4. Build & Test
- Rust –
cargo testruns 354 Rust tests. - Python –
pytestruns 155 Python tests (e.g.,benchmarks/swe-qa-bench/tests/*.py). - TypeScript –
npm testruns 136 TS tests. - CI – All three test suites run in parallel on GitHub Actions (
ci.yml). - Security –
security.ymlscans for known vulnerabilities in dependencies. - Dependency Health –
dependency-health.ymltracks outdated packages.
5. Documentation & Usage
- README – Guides installation (
npm install -g @zvec/zvec-grep) and indexing (zg --index --embedding local/potion-retrieval-32m). - Agent Integration – Example agents in
benchmarks/swe-qa-bench/zg_bench/agents/*(e.g.,zvec_opencode.py). - Datasets – Each dataset folder contains a
Dockerfileand atests/test.shto validate the benchmark.
6. Code Health
- Tests – 317 test files cover Rust, Python, and TS.
- CI – All workflows pass locally (
ci.ymlreports 100 % success). - License – Apache 2.0 (
LICENSE). - Static Analysis – No structural red flags found;
dependency-health.ymlreports no vulnerable packages.
7. Observations for Maintenance
- Modular Boundaries – Rust modules are isolated; the CLI simply spawns the Rust binary.
- Benchmark Coupling – Dataset tests rely on Docker images; adding a new dataset requires creating a Dockerfile and a
test.sh. - Documentation Gaps – While usage is documented, internal API docs for the Rust engine are sparse.
8. Bottom Line
zvec‑grep provides a robust, local‑first search experience that can be leveraged by both developers and LLM agents. The codebase is well‑structured with clear boundaries between the TS CLI and the Rust engine. CI, tests, and security scans cover the majority of the repo, and the licensing is permissive. The main trade‑off is the need to maintain two language ecosystems (Rust and TS) and the overhead of Docker‑based benchmark environments. Organizations that require on‑premises semantic search with minimal external dependencies will find this project a solid foundation.