CocoSearch: local code search を agent 用の hybrid retrieval layer にする
Agent に知らない codebase を探索させるとき、面倒なのは「検索すること」そのものではない。検索結果が細かすぎて、判断に使える形になっていないことだ。
「authentication flow はどこか」と聞くと、agent はまず auth を grep し、次に login を grep し、いくつか file を読んで、実際の名前が session_renewal だったと気づく。「この config parser を変えるとどこに影響するか」と聞くと、今の file は見つけられても reverse dependency や call boundary までは分からない。結果として、多くの token が試行錯誤の file reading に使われ、本当に判断と edit に必要な context が薄くなる。
今日メモしておきたい VioletCranberry/coco-search は、local 寄りで実用志向の code retrieval layer だ。新しい chat app ではない。Codebase を index し、CLI、Web dashboard、interactive REPL、MCP tools として公開する。Agent は natural language で code を検索でき、language、symbol type、dependency impact といった制約も付けられる。
GitHub repository API、README、release page、license file、tag list、default branch の shallow clone から 2026-07-06 に確認できる公開情報では、CocoSearch は現在 36 stars、6 forks。repository の主言語は Python、license は MIT、作成日は 2026-02-16。直近 push は 2026-07-05 09:52 UTC。最新 release は v0.1.48 で、GitHub release page 上の公開時刻は 2026-06-04 16:51 UTC。
Project Overview
| 属性 | 内容 |
|---|---|
| Repository | VioletCranberry/coco-search |
| 位置づけ | local-first hybrid code search CLI / Dashboard / MCP server |
| Stars | 36 |
| Forks | 6 |
| 主言語 | Python |
| License | MIT |
| Repository 作成日 | 2026-02-16 |
| Latest push | 2026-07-05 09:52 UTC |
| Latest version | v0.1.48 |
| Release time | 2026-06-04 16:51 UTC |
| 核心アイデア | vector retrieval、full-text search、symbol filtering、dependency graph で agent に少なくて精度の高い code context を渡す |
semantic search だけではなく hybrid retrieval
CocoSearch の README でまず目に入るのは、「semantic search だけ」を答えにしていないところだ。
Retrieval pipeline は pgvector の vector similarity と PostgreSQL tsvector の full-text search を組み合わせ、Reciprocal Rank Fusion で ranking を merge する。Code search ではこれはかなり現実的だ。Natural language question には semantic matching が必要だが、function name、class name、config key、error code には keyword の正確さも必要になる。
たとえば “authentication middleware” と検索すると、vector search は login state を扱う関数を見つけるかもしれない。一方で repository に AuthMiddleware、auth_middleware、validateAuthHeader があるなら、keyword と identifier analysis も捨てるべきではない。CocoSearch は camelCase、snake_case、PascalCase のような code identifier を検出し、symbol type、symbol name、language での filtering も持っている。
これは単に code chunk を vector database に入れるより、かなり engineering tool に近い。Code は普通の document ではない。名前、boundary、definition location、dependency relationship が重要だ、という前提に立っている。
Tree-sitter で結果がただの行番号になりにくい
多くの code search tool は「match した数行」を返す。ただ、その数行が意味のある単位とは限らない。Agent はその fragment を見たあと、さらに上、下、関連定義を読まないと、本当に使える結果か判断できない。
CocoSearch は Tree-sitter で context expansion を行う。README によると、検索結果を周囲の function/class boundary まで広げられるので、任意の行番号付近だけが返ってくる状態を避けやすい。Parse health も管理し、どの file が正常に parse できたか、部分的に parse されたか、grammar がないかを見られる。
これは agent との相性がよい。Agent が知りたいのは「ここに auth という文字列がある」だけではない。その match がどの function に入っているのか、function が何をしているのか、definition なのか call なのか、現在の language structure として信頼できるのかだ。実際の code structure に近いほど、agent が後続で間違った file を読み続ける確率は下がる。
dependency graph が普通の検索より一歩先に進めている
もう 1 つ面白いのは dependency graph だ。
CocoSearch は検索結果を返すだけではなく、file-level dependency extraction も持っている。README では Python、JavaScript/TypeScript、Go、Terraform、Helm、GitHub Actions、GitLab CI、Docker Compose、ArgoCD、Markdown などの extractor が挙げられており、forward dependency tree と reverse impact analysis も提供されている。
つまり「code を見つける」だけでなく、「ここを変えると誰に当たるか」に近づいている。たとえば次のような場面だ。
- GitHub Actions workflow を変える前に、依存している script や config を見る;
- TypeScript module を変える前に、どの file が reverse dependency を持つか調べる;
- Agent に PR review をさせるとき、diff だけでなく blast radius も見せる;
- 複数 repository の index をつなぎ、cross-index search を行う。
この能力は MCP に向いている。Agent はまず search_code で候補位置を見つけ、そのあと dependency/impact tool で変更範囲を確認できる。Shell 上で不安定な grep を何度もつなぐより、workflow として扱いやすい。
導入経路は developer 向けに整理されている
CocoSearch の入口は比較的はっきりしている。README には 2 つの service path がある。Local Ollama embedding を使う方法と、OpenAI/OpenRouter のような remote embedding provider を使う方法だ。Storage には PostgreSQL + pgvector が必要で、Docker Compose で立ち上げられる。
Interface もいくつか用意されている。
- CLI:
uvx cocosearch index /path/to/projectとuvx cocosearch search "authentication flow" --pretty; - Web dashboard: 複数 project の管理、index 作成、highlighted result、chart、log の確認;
- Interactive REPL: 条件を変えながら連続して検索する探索向け;
- MCP server: Claude Code、Claude Desktop、OpenCode などの MCP client から呼ぶ。
それぞれ違う作業に向いている。単発 query は CLI、index の状態確認は dashboard、retrieval quality の調査は analyze、agent workflow への接続は MCP。小さな project としては、interface の幅はかなり広い。
どんな場面に合うか
CocoSearch が合いそうなのは大きく 3 種類の user だと思う。
1 つ目は、すでに coding agent を使っている developer。Agent が「場所を探す」ために何ラウンドも消費している、特に大きめの Python、TypeScript、Go、Rust、IaC repository で grep を行き来している、という場合に local search tool として足せる。
2 つ目は、複数 project をまたいで保守する人。Cross-index search と dashboard の multi-project management があるので、service、library、config repository を同時に扱う workflow に意味がある。
3 つ目は、retrieval quality を自分で観察したい人。analyze、parse health、pipeline diagnostics、cache、symbol filter などがあるので、「なぜこの結果が上に来たのか」を追いやすい。Black-box RAG より engineering debug に向いている。
注意点
第一に、zero-dependency な小さな script ではない。主要機能を使うには PostgreSQL + pgvector が必要で、default の local embedding には Ollama も使う。Docker Compose で起動コストは下がっているが、pure CLI grep wrapper よりは重い。
第二に、project はかなり新しい。Repository 作成日は 2026-02-16 で、現時点の stars は 36。最新 release は v0.1.48 で、version からも速く変わっていることが分かる。試用や小さな導入には向くが、評価なしに強い production dependency にする段階ではない。
第三に、README に載っている能力範囲は広い。Hybrid retrieval、dependency graph、dashboard、MCP、Claude skills、PR review まである。広いことは魅力でもあるが、自分の repository で実際に動かし、必要な language と workflow が十分支えられているか確認したほうがよい。
第四に、semantic retrieval にはまだ人間の判断が必要だ。CocoSearch は blind search を減らせるが、code reading、test、review の代わりにはならない。Agent が検索結果を受け取ったあとも、重要 file を読み、dependency relationship を確認し、project 固有の check を走らせるべきだ。
まとめ
CocoSearch が気になるのは、agent code search の実際の痛点をいくつかまとめて扱っているからだ。Natural language は正確な名前を知らない。Keyword search は intent に弱い。Vector search は symbol boundary を知らない。grep は reverse impact を教えてくれない。
これらを local index にし、CLI、dashboard、MCP から使えるようにする方向はかなり実用的だ。Agent が突然 system 全体を理解するわけではない。ただ、試行錯誤の file digging を少し減らし、構造を持った context を渡しやすくなる。
すでに実 repository で coding agent を使っていて、探索、bug fix、diff review、dependency impact analysis をよく任せているなら、CocoSearch は複雑だが重要すぎない project で試す価値がある。工程判断を置き換える tool ではなく、「code を探す」段階を guessing から tool call に近づけるものとして見るのがよさそうだ。