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

LayerFilesToolingNotes
CLI & Agentssrc/ (136 TS files)npm, TypeScriptzg is installed globally via npm install -g @zvec/zvec-grep.
Rust Enginerust/ (601 Rust files)CargoPerformance‑critical components (e.g., indexing, query execution).
Benchmarksbenchmarks/Python + RustTwo suites: browse‑comp‑plus and swe‑qa‑bench.
Python Utilitiesbenchmarks/.../datasets/.../DockerfileDockerEach dataset ships a container that builds environment and runs tests.
CI.github/workflows/*GitHub Actionsci.yml, rust-ci.yml, security.yml, dependency‑health.yml, benchmark‑* workflows.

3. Entry Points

  • CLI – zg (installed via npm). The underlying script is src/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 test runs 354 Rust tests.
  • Python – pytest runs 155 Python tests (e.g., benchmarks/swe-qa-bench/tests/*.py).
  • TypeScript – npm test runs 136 TS tests.
  • CI – All three test suites run in parallel on GitHub Actions (ci.yml).
  • Security – security.yml scans for known vulnerabilities in dependencies.
  • Dependency Health – dependency-health.yml tracks 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 Dockerfile and a tests/test.sh to validate the benchmark.

6. Code Health

  • Tests – 317 test files cover Rust, Python, and TS.
  • CI – All workflows pass locally (ci.yml reports 100 % success).
  • License – Apache 2.0 (LICENSE).
  • Static Analysis – No structural red flags found; dependency-health.yml reports 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.