zvec-grep：人間と agent が共有する local code search layer
大きな repository を AI coding agent に読ませるとき、問題は「検索できない」ことよりも「検索が散らばる」ことにある。まず全体 grep、次に大量の file open、それでも context が足りずもう一度広く探す。人間がコードを調べるときも似ている。関数名が分かっていれば rg は速いが、意味は分かるのに keyword が分からない場面では勘に頼ることになる。さらに、人間と agent が別々の入口を使うと、index、permission、evidence format も分かれてしまう。
今日見るのは zvec-ai/zvec-grep。Command 名は zg。Local-first workspace search layer として、ripgrep、BM25 full-text search、vector search を一つの CLI / MCP interface の後ろにまとめる。README の考え方は分かりやすい。同じ workspace を一度 index し、人間は terminal から検索し、agent は MCP 経由で同じ local index と同じ検索ルールを使う。
GitHub repository API、README、package.json、latest release、tags、commits API を 2026-08-30 18:04 Asia/Shanghai 時点で確認すると、zvec-ai/zvec-grep は 23 stars、4 forks。主要言語は TypeScript、license は Apache-2.0、default branch は main、repository 作成日は 2026-07-10 02:58:07 UTC、latest push は 2026-08-28 08:42:13 UTC。最新 commit は 8551a93、commit time は 2026-08-28 05:39:40 UTC、内容は BrowseComp benchmark result の更新。Latest GitHub Release は v0.2.0、published time は 2026-08-27 16:15:11 UTC。package.json の npm package name は @zvec/zvec-grep、version も 0.2.0、runtime requirement は Node.js 22+ だ。
プロジェクト概要
| 項目 | 内容 |
|---|---|
| リポジトリ | zvec-ai/zvec-grep |
| 位置づけ | CLI user と AI agent 向けの local-first hybrid workspace search layer |
| Stars | 23 |
| Forks | 4 |
| 主要言語 | TypeScript |
| ライセンス | Apache-2.0 |
| 作成日 | 2026-07-10 02:58:07 UTC |
| Latest push | 2026-08-28 08:42:13 UTC |
| 最新 commit | 8551a93、2026-08-28 05:39:40 UTC |
| 最新 Release | v0.2.0、2026-08-27 16:15:11 UTC |
| キーワード | ripgrep、BM25、vector search、MCP、local-first、agent search |
解いているのは検索入口の分裂
zvec-grep は ripgrep を置き換えようとしているわけではない。Exact search と semantic discovery を同じ tool に入れるのが狙いだ。Identifier、path、regex が分かっているなら managed ripgrep を使う。逆に「theme preference はどこで restore されるのか」のように意図だけ分かっているなら、indexed search が BM25 と vector retrieval を組み合わせて rank し、source location 付きの短い evidence を返す。
この設計は人間にも agent にも効く。人間は普段 rg、IDE search、document search を行き来する。Agent は entry file が分からないとき、検索範囲を何度も広げがちだ。zvec-grep の価値は、二種類の query があることを正面から扱う点にある。Exact text は deterministic な tool で探す。Semantic exploration は index で候補を絞る。この二つを統一するほうが、agent に別の vector database を追加するより実用的だ。
README に出てくる result format も大事だ。Default output は意図的に compact で、ranking、file grouping、source location、bounded preview を含む。--human は terminal user 向けに読みやすい出力を返す。同じ retrieval layer を使い、表示密度だけを変える。この形は、大量の file content を model context に流し込むより扱いやすい。
MCP integration が主役になっている
多くの search tool は agent から呼び出せるが、zvec-grep は agent integration をかなり前面に出している。v0.2.0 release note では Codex、Claude Code、Qwen Code、OpenCode、Cursor の managed MCP integrations が挙げられている。README の zg install は supported agent を検出して設定し、--target codex や --target qwen のように明示指定することもできる。
実用的なのは、installer が MCP tool を公開するだけではなく retrieval guidance も設定することだ。Agent が semantic search を使うべき場面、exact lookup を使うべき場面、両方を組み合わせる場面、そして evidence が十分になった時点を判断しやすくする。Agent にとって tool があるだけでは足りない。無駄な scan、無駄な file read、無関係な context を減らすには、使い方の guidance が重要になる。
Local server mode もこの方向に沿っている。zg server on で shared local service を起動し、workspace runtime、background refresh、MCP access、loaded embedding model を調整できる。CLI operation は auto、server、direct mode を選べる。一方で managed ripgrep は index や embedding model なしでも動く。これはよい fallback だ。Semantic index の準備ができていなくても、exact search は残る。
local-first の境界が明確
zvec-grep の README は local-first を何度も強調している。Workspace scanning、index storage、retrieval、local embedding inference は default で local machine に残る。Shared service は loopback を listen し、index は <workspace>/.zvec-grep/ に保存される。Remote Qwen text / multimodal embedding も supported だが、workspace content や query text を remote provider に送るには別途 explicit authorization が必要だ。
Code search tool にとって、これは単なる飾りではない。Workspace には customer code、configuration、experiment note、internal document、一時的な credential trace が混ざることがある。Index と model call を default で local に置くなら、sensitive repository でもまず controlled experiment を始めやすい。最初から data egress approval で止まる可能性が下がる。
また、検索対象は source code だけではない。Markdown、JSON、YAML、TOML、CSV、HTML、XML、plain text に加え、複数言語の structure-aware extraction も扱う。Agent にとってこれは重要だ。実際の質問は code、config、README、ADR、test fixture をまたぐことが多い。.ts や .py だけを index すると、設計意図を説明している material を落としやすい。
benchmark は見る価値があるが、過信は禁物
Repository には SWE-QA-Bench と BrowseComp-Plus の paired A/B benchmark があり、release note でも answer quality、input tokens、tool calls、agent execution time、traces を比較軸にしている。README の case study は Pylint、Matplotlib、Django。Semantic discovery で search space を絞り、lexical retrieval で exact identifier を anchor し、compact evidence で broad scan を減らす、という主張だ。
これらの benchmark は project direction を判断する材料になる。作者は見た目のよい CLI だけを作っているのではなく、「better retrieval layer が agent の context waste を減らせるか」を検証しようとしている。ただし project はまだ preview stage だ。Benchmark result は方法と再現性を見るべきで、一般的な保証として読むべきではない。Model、repository structure、question type によって効果は変わる。
向いている人
一つ目は、中規模以上の codebase をよく触る developer だ。rg には慣れているが、「だいたい何が起きているかは分かるが keyword が分からない」検索で詰まることがある。zg query --human は semantic discovery layer として使い、最後は exact file と line で確認する、という流れが作れる。
二つ目は、AI coding agent の toolchain を整えている人だ。Agent に境界なく grep させるより、short evidence を返し、exact / semantic route を選べ、index を再利用できる MCP tool を渡すほうがよい。特に問題が複数 file、module、document をまたぐとき、この種の retrieval layer は価値が出やすい。
三つ目は、data egress に敏感な小さな team だ。Node.js 22+、npm global install、local index、local model catalog、explicit remote authorization という制約は、すぐ managed search platform を導入するより、まず single machine や小チームで試すのに向いている。
Caveats
第一に、かなり新しい。Repository は 2026-07-10 作成、stars は 23、latest release v0.2.0 も public preview と明記されている。CLI、MCP contract、configuration default、index compatibility、installation behavior は今後も変わる可能性がある。
第二に、runtime requirement がある。package.json と README は Node.js 22 or newer を要求している。Team の machine や CI image が古い Node LTS に残っているなら、まず基盤環境を更新する必要がある。
第三に、semantic retrieval は万能ではない。Entry point が不明、evidence が分散している、cross-file understanding が必要な問題には向く。一方で、関数名や固定文字列を探すだけなら managed ripgrep のほうが確実だ。うまく使うには、人間も agent も、まず evidence を見てから file を開く習慣が必要になる。
まとめ
zvec-ai/zvec-grep が面白いのは、「agent に code search を渡す」ことを閉じた vector index として作らず、rg、BM25、vector search、MCP guidance、local server を一続きの workflow にしている点だ。人間も使える。Agent も使える。Exact lookup も semantic exploration も使える。Default は local で、remote embedding は必要なときに明示して使う。
まだ preview stage なので、critical workflow に何も考えず入れる段階ではない。それでも、agent が repository を読むときの search が散らかる、context waste が大きい、あるいは人間の検索が「意味は分かるが keyword が分からない」で止まるなら、zvec-grep は試す価値がある小さな tool だ。
プロジェクトアドレス：https://github.com/zvec-ai/zvec-grep