Shebe：coding agent に local BM25 code search layer を渡す
AI coding agent が code を探すとき、すべての問題に semantic search が必要なわけではない。
function name、error message、API name、config key、log fragment がすでに分かっているなら、いちばん強いのは今でも keyword search だ。ただし plain grep は速い一方で、output が平たい。file path、line number、match line が大量に出て、agent はそこからまた file を読み、filter し、summary を作る必要がある。人間ならざっと見られるが、agent には tool call と token cost として積み上がる。
今日メモしておきたい shebe-oss/shebe は、このかなり素朴な隙間を狙っている。coding agent に local で高速な BM25 code search layer を渡す project だ。vector database でも code understanding platform でもなく、Rust で書かれた CLI と MCP server として、local repository から ranked result、reference candidate、file preview、paginated read を返す。
2026-07-15 時点で GitHub repository page、README、Releases page、Tags page、commit history、LICENSE、GitHub page metadata から確認できる公開情報では、shebe-oss/shebe は 35 stars、3 forks。主言語は Rust、license は Apache-2.0。repository 作成日は 2025-12-28 03:51:24 UTC、最近の public push は 2026-07-13 17:52:06 UTC。default branch main の最新 commit は 7166911、commit time は 2026-07-13 17:52:04 UTC。GitHub Releases page の latest release は v0.5.8 で、Tags page でも latest tag は v0.5.8、日付は 2026-02-03 だ。
プロジェクト概要
| 項目 | 内容 |
|---|---|
| リポジトリ | shebe-oss/shebe |
| 位置づけ | coding agent 向けの local BM25 code search CLI / MCP server |
| Stars | 35 |
| Forks | 3 |
| 主言語 | Rust |
| ライセンス | Apache-2.0 |
| リポジトリ作成日 | 2025-12-28 03:51:24 UTC |
| 最近 push | 2026-07-13 17:52:06 UTC |
| 最新 main commit | 7166911、2026-07-13 17:52:04 UTC |
| Latest GitHub release | v0.5.8、2026-02-03 |
| 最新 tag | v0.5.8 |
| 主な入口 | brew tap shebe-oss/tap、brew install shebe、shebe index-repository、shebe search-code、shebe-mcp |
| キーワード | BM25、local-first、MCP、code search、ranked results、Rust |
なぜまた vector search ではないのか
Shebe README の問題設定はかなり明確だ。developer の code search の多くは、正確な term に価値がある。探したいものは AuthorizationPolicy、SubstitutionFormatter、特定の error message、ある config key かもしれない。この場合、agent が query を embedding に変換し、semantic similarity から候補を推測する流れは、必ずしも keyword model より直接的ではない。
BM25 のよさは、地味で、説明しやすく、安いところにある。query term が document のどこに出るか、どのくらい出るか、document length はどうかを見て rank する。code repository では、この ranking が agent にとって plain grep より扱いやすい。すべての match line を一気に渡すのではなく、関連度の高い候補から読ませられるからだ。
Shebe は、自分の境界も広げすぎていない。README では grep/ripgrep と Serena のような structural tool の間に置いている。grep は exact regex と小さな codebase に強い。Serena は AST / LSP aware な symbol refactoring に向く。Shebe は large codebase、polyglot search、boolean query、ranked result が必要な content search 向けだ。この境界の切り方は、「万能 AI search」より信用しやすい。
人間向け CLI だけでなく、agent 向け interface がある
Shebe には二つの入口がある。人間は CLI で直接使える。
shebe index-repository ~/envoy envoy-v1
shebe search-code envoy-v1 "accesslog format"agent は MCP 経由で使える。README にある tool set には search_code、find_references、find_file、read_file、preview_chunk、list_dir、reindex_session などがあり、合計 14 個の MCP tools として説明されている。ここで実用的なのは、結果を巨大な file content として返すのではなく、比較的小さな token budget に収め、pagination も持たせている点だ。
これは coding agent には重要だ。普通の workflow では、agent が grep で数十 file を見つけ、次にそれぞれを read file し、最後に本当に関係があるものを判断する。Shebe は ranked candidate と low-token preview を tool layer に置くことで、agent が search result を機械的に整理する時間を減らそうとしている。
README の performance target もかなり engineering 寄りだ。millisecond-level query、数千から一万 files/sec 単位の indexing、query あたり数百 token 程度の output が説明されている。これをすべての repository に対する保証として読むつもりはないが、project が demo より agent workflow cost を見ていることは分かる。
local-first で、代償もはっきりしている
install path は素直だ。macOS と Linux では Homebrew tap が使える。
brew tap shebe-oss/tap
brew install shebeLinux x86_64 には manual download の release package もある。indexing には repository を local に clone してから index-repository で session を作る必要がある。README は二つの制限もはっきり書いている。remote URL を直接 index するのではなく local clone が必要なこと、そして BM25 は semantic similarity ではないので login が自然に authenticate に一致するわけではないことだ。
この制限が明示されているのはむしろよい。Shebe を使うべき場面と、使わない場面が分かるからだ。known symbol、API、error text、config item、cross-language keyword を探すなら向いている。逆に「user authentication の concept はどこにあるか」のような質問には、semantic search や structural tool を組み合わせる方がよい。
local-first であることも価値になる。index と query は local machine で完結し、private repository を cloud service に渡さなくてよい。多くの team にとって、code search の問題は「できるか」だけでなく「code が境界の外へ出るか」でもある。Shebe の trade-off は、private codebase で小さく試すにはちょうどよい。
grep、Serena との関係
WHY_SHEBE document では、Istio と Eigen を使った refactoring scenario で grep/ripgrep や Serena と比較している。そこで示したいのは「grep が悪い」ではない。agent が search result を変更計画に変換するとき、raw grep output はかなり manual synthesis を要求する。一方で LSP / AST tool は、language や macro によって抜けが出る場合がある。BM25 と reference-oriented tools は、その中間で agent が消費しやすい candidate set を返せる、という主張だ。
この評価には少し警戒も必要だ。benchmark は常に自分に有利な task を選べるし、language、query、symbol shape によって結果は変わる。それでも、問題提起は本物だ。agent の bottleneck は tool execution speed そのものより、tool output が散らばりすぎて、その後の reading と judgment が高くつくことにある。
だから Shebe を ripgrep replacement と見るつもりはない。人間にとって rg は今でも第一選択だ。Shebe は agent のための ranked search adapter に近い。本来 agent が自分で整理していた grep result を、より structured で token-efficient な tool response に変える。
向いている場面
第一の場面は、大きな repository で known term を探すときだ。error code、log fragment、API name、feature flag、config key、type name。探す言葉は分かっているが、agent に無関係な match を大量に読ませたくない場合に向いている。
第二の場面は、polyglot repository だ。Shebe は特定の LSP に閉じず、README でも polyglot search を強調している。Go と YAML、TypeScript と config file、Rust と documentation のような repository では、content search が pure symbol tool より安定することがある。
第三の場面は、すでに MCP agent を使っている場合だ。Shebe の価値は CLI だけではなく、Claude Code、Codex、その他 MCP client の retrieval backend になれるところにある。agent が変更前に reference と context を確認しやすくなる。
第四の場面は、private codebase だ。SaaS account も cloud indexing も不要なので、security boundary に敏感な team でも試しやすい。
注意したいところ
第一に、project はまだ小さい。35 stars、3 forks。main branch には 2026-07-13 の documentation update があるが、外部の利用例はまだ多くない。採用するなら version を pin し、non-critical repository から試したい。
第二に、BM25 は semantic understanding ではない。agent にはよい query を作らせる必要がある。必要なら synonym、API name、error text、concrete type name を追加する。README も、本当に semantic similarity が必要な場合は vector tool と組み合わせることを勧めている。
第三に、local clone と indexing session が必要だ。GitHub URL を cloud service に渡すより一手間かかる。ただし、その代わりに local control と data leakage risk の低さが得られる。
第四に、latest GitHub release v0.5.8 は 2026-02-03 のものだが、main branch は 2026-07-13 にも更新されている。release package と main branch documentation の状態を分けて見た方がよい。
まとめ
Shebe が面白いのは、派手な「agent がすべて理解する」方向ではなく、known keyword search を agent が消費しやすい形にするという、地味だが実用的な位置を選んでいるところだ。
coding agent が大きな repository で symbol、error string、API name を探すために何度も grep し、file を読み、context を絞り込んでいるなら、shebe-oss/shebe は試す価値がある。小さく、境界が明確で、完全に local。MCP toolbox の中で「まず関連 code を ranked に並べる」基礎 layer として使えそうだ。