AI coding agent が code を書くとき、本当に時間を使うのは patch そのものではなく、「この repository では何がどこにあるのか」を理解するところだったりする。Business question を投げると、まず grep し、関連していそうな file をいくつか開き、ようやく本当の entry point が別 package にあることに気づく。Context window がどれだけ大きくなっても、毎回 codebase 全体を詰め直すのは健全ではない。

より実務的なのは、codebase を local で query できる evidence set に変えることだ。Semantic search は概念を探す。Keyword index は identifier をつかむ。Symbol lookup は definition に落とす。Call graph は caller / callee を追う。Branch-aware index は別 branch の結果を混ぜないようにする。

今日見るのは Helweg/open-codebase-index。OpenCode、Codex、Claude Code、Pi、Jcode、MCP clients 向けの local codebase indexing tool で、TypeScript が host integration、configuration、indexing orchestration、tool layer を担当し、Rust native module が tree-sitter parsing、vector storage、SQLite、BM25、hashing、call extraction を担当する。README の位置づけは明快で、意味で codebase を検索し、その結果から definitions、callers、dependency paths へ進むための tool だ。

GitHub repository API、README、LICENSE、Releases page、recent commit を 2026-08-17 10:00 Asia/Shanghai 時点で確認すると、Helweg/open-codebase-index は 167 stars、31 forks。主要言語は TypeScript で、language stats には Rust、JavaScript、Tree-sitter Query、Shell も含まれる。GitHub repository API は license を MIT と報告し、LICENSE file も MIT License だ。Repository created time は 2026-01-13 15:29:07 UTC、latest public push は 2026-08-17 05:59:25 UTC、default branch は main。GitHub Releases の latest stable release は v0.23.0、published time は 2026-08-11 12:57:38 UTC。Recent commit は d23f2a9、message は fix(indexer): skip unreadable files instead of aborting the whole index (#297)、commit time は 2026-08-17 05:59:24 UTC。

プロジェクト概要

項目内容
リポジトリHelweg/open-codebase-index
位置づけLocal semantic code index、BM25、symbol lookup、call graph tool
Stars167
Forks31
主要言語TypeScript
その他の言語Rust、JavaScript、Tree-sitter Query、Shell
ライセンスMIT
作成日時2026-01-13 15:29:07 UTC
Latest push2026-08-17 05:59:25 UTC
Default branchmain
Latest Releasev0.23.0、2026-08-11 12:57:38 UTC
Recent commitd23f2a9、fix(indexer): skip unreadable files instead of aborting the whole index (#297)
キーワードcode search、MCP、semantic search、BM25、tree-sitter、SQLite、Rust native

これは「もう一つの grep」ではない

open-codebase-index が面白いのは、codebase query を複数の tool に分けている点だ。単一の similarity search box だけを提供しているわけではない。README に並ぶ capability には semantic retrieval、hybrid retrieval、codebase_context、codebase_peek、implementation_lookup、call_graph、call_graph_path、pr_impact がある。この設計の前提は実務的だ。Agent が投げる質問は、いつも同じ種類ではない。

Business concept だけ分かっていて function name が分からないときは semantic search が効く。Symbol name がすでに分かっているなら、embedding に推測させるより definition を直接探すべきだ。Change impact を見たいなら、call graph や dependency path が必要になる。Agent が欲しいのが low-token の candidate file pack だけなら、source body 全文を返す必要はない。

ここが普通の full-text search より agent workflow に向いている部分だ。人間の developer は IDE で自由に jump できるが、agent には構造化された tool layer が必要になる。「まずどの file を見るべきか」「どの function が authoritative definition か」「call chain はどう流れるか」「この branch の index は fresh か」を tool が返せると、model は探索だけで context を燃やさずに済む。

Local index なので private repository でも試しやすい

README の quick start はかなり直接的で、Node.js 20 以上が前提だ。

npm install open-codebase-index

OpenCode では opencode.json に plugin として追加し、/status と /index から始められる。MCP clients では open-codebase-index-mcp を使う。Codex、Claude Code、Pi、Jcode、Cursor、Windsurf では configuration path がそれぞれ違うが、基本は同じだ。Index は project 近く、または host ごとの directory に置かれ、agent は tool call で query する。

Storage の組み合わせも実用寄りだ。SQLite metadata、usearch vectors、BM25 inverted index、さらに tree-sitter から得た chunks、symbols、call extraction を使う。README では TypeScript、JavaScript、Python、Rust、Swift、Go、Java、C#、Ruby、C/C++、PHP、Bash、Zig、JSON、Markdown など多くの言語に触れており、完全に parse できない場合は text fallback がある。

Private codebase では、この形は「repository を外部の code understanding SaaS に渡す」より評価しやすい。Embedding provider として OpenAI、Google、custom OpenAI-compatible endpoint などを使う可能性はあるが、index、file discovery、BM25、graph structure は local にある。Ollama を選んで local embedding から始めれば、data boundary をさらに狭くできる。

Branch-aware は地味だが重要

多くの code indexing demo は見た目が良いが、実際の開発に入れると branch 問題に当たる。昨日 feature branch で作った index を、今日 main に戻っても agent が使い続けるなら、時間を失うだけでなく、違う file を直してしまう可能性もある。

open-codebase-index の README は branch-aware indexing を明示している。Content hash で変わっていない chunk を reuse しながら、branch catalogs を持ち、results を active branch に揃える。Linked worktree にも対応した strategy がある。派手な selling point ではないが、maintainer が日常の repository で本当に使っていそうな detail だ。

Latest commit からも、この engineering posture が見える。d23f2a9 は unreadable files があると indexing run 全体が abort する問題を直している。OS level で読めない file に当たったら、indexer は skip して記録すべきで、全体を落とすべきではない。この修正は小さいが、code indexer が扱う現実をよく示している。Permission、watcher、worktree、大きな directory、GUI editor の environment variable は、agent が安定して context を取れるかどうかに直結する。

使いどころ

一つ目は、「この挙動はどこで実装されているのか」を agent に素早く探させる場面だ。Function name が分からず、business path だけを説明できるとき、codebase_context や hybrid retrieval で候補を出し、implementation_lookup で definition に落とせる。

二つ目は、変更前の impact check だ。Authentication state、queue scheduling、cache invalidation などを触るとき、単一 file だけ見ても足りない。Call graph と dependency path があれば、agent は callers、callees、関連 tests を先に見てから patch scope を決められる。

三つ目は、複数の agent host 間で code understanding layer を共有する場面だ。README は OpenCode、Codex、Claude Code、Pi、Jcode、generic MCP clients を同時に扱う。Team が複数の CLI / editor agent を混ぜているなら、index layer を同じ local tool に寄せることで、各 host が毎回 repository を探索し直すコストを減らせる。

Caveats

第一に、まだ若い project だ。Repository created time は 2026-01-13、stars は niche range にあり、latest release は v0.23.0。Version number から見ても API や behavior はまだ動き続ける可能性がある。Production team は、まず非クリティカルな repository で試す方がよい。

第二に、embedding provider の選択が privacy、latency、retrieval quality に直結する。README は Ollama、OpenAI、Google、GitHub Copilot、custom endpoint を扱うが、それぞれ trade-off が違う。「local index」と言っても、設定次第では embedding request が外へ出る。Provider 設定はきちんと確認したい。

第三に、code index は自動的に正しいわけではない。Large repository、generated code、vendored dependency、permission error、branch switch、worktree は noise を生む。open-codebase-index はそれらを扱おうとしているが、使う側も agent に retrieval result を evidence として扱わせる必要がある。最終結論ではなく、調査を始めるための根拠として見るべきだ。

まとめ

Helweg/open-codebase-index が注目に値するのは、agent code search を単なる「semantic search box」に閉じ込めていないからだ。Real code understanding には keyword、embedding、symbol、call graph、branch freshness、low-token context pack という複数の evidence が必要だ、という前提に立っている。

Codex、Claude Code、OpenCode、その他 MCP client で同じ repository を agent に何度も読ませているなら、この project は local index layer として試しやすい。最も向いているのは、「model に repository 全体を持たせる」ことではない。作業前に信頼できる入口を素早く見つけ、path を推測する時間と branch の読み違いを減らし、本当に変更すべき code に context を使うことだ。

リポジトリ：https://github.com/Helweg/open-codebase-index