CodeRAG：coding agent に local-first な semantic code index を持たせる
AI coding agent がよく無駄にする時間の一つは、慣れていない repository で grep、find、file read、keyword の変更を繰り返すことだ。この方法は動くが、「context を探す」だけで token と round-trip をかなり使う。keyword が少しずれると、本当に関係する function や file を逃すこともある。IDE の symbol jump は一部を解決するが、同じ検索能力を CLI、HTTP service、Web UI、MCP server に持ち込みたいなら、もう少し独立した code indexing layer が欲しくなる。
今日紹介する Neverdecel/CodeRAG は、そのための project だ。local-first な semantic code-search engine として、codebase を hybrid search index に変換する。local ONNX embedding による vector retrieval と BM25 keyword retrieval を組み合わせ、path:line 付きで functions、classes、methods、file snippets を返す。agent にとって大事なのは「検索が格好いい」ことではなく、毎回 grep loop を作り直す代わりに、warm index を一回 query できることだ。
2026-07-21 時点で GitHub repository API、README、LICENSE、tags API、public commits API から確認できる情報では、Neverdecel/CodeRAG は 234 stars、37 forks。GitHub の primary language は Python、license は Apache-2.0。repository creation time は 2024-09-08 09:29:33 UTC、GitHub repository pushed_at は 2026-07-14 11:26:54 UTC。default branch は master。public commits API が返す default branch の最新 commit は ab0bb12、commit time は 2026-06-21 16:33:53 UTC、message は Derive store_dir from watched_dir instead of the cwd (#62)。GitHub releases latest endpoint は 404、tags API は empty array を返したため、現在確認できる GitHub release/tag はない。
プロジェクト概要
| 項目 | 内容 |
|---|---|
| リポジトリ | Neverdecel/CodeRAG |
| 位置づけ | local-first semantic code search、RAG、agent retrieval layer |
| Stars | 234 |
| Forks | 37 |
| 主言語 | Python |
| ライセンス | Apache-2.0 |
| GitHub 作成時刻 | 2024-09-08 09:29:33 UTC |
| repository pushed_at | 2026-07-14 11:26:54 UTC |
| default branch | master |
| default branch 最新 commit | ab0bb12、2026-06-21 16:33:53 UTC |
| GitHub release/tag | 現在確認できる release/tag はなし |
| キーワード | semantic code search、hybrid retrieval、BM25、embeddings、MCP、local-first |
単なる grep replacement ではない
CodeRAG の README は問題設定をかなり直接書いている。coding agent は code を探すために grep、glob、read を何度も繰り返しがちで、それが multiple tool calls と context noise を生む。CodeRAG の approach は、先に workspace を warm index にしておき、agent が一つの query で ranked candidate locations を受け取れるようにすることだ。default retrieval は pure vector でも pure keyword でもなく、dense vector search と BM25 を reciprocal rank fusion で合わせる。
この選択は実務的だ。pure vector search は「retry/backoff はどこで扱われているか」のような semantic question に強いが、具体的な identifier、config key、error code では不安定になりやすい。pure keyword search は exact string には強いが、「この種類の logic はどこか」という問いには弱い。hybrid search は両方を合わせるので、codebase search の実際の使い方に近い。
symbol-aware chunking も重要だ。Python は ast、JS/TS、Go、Rust、Java などは tree-sitter を使い、functions、classes、methods を自然な index unit として扱う。固定長 text chunk を機械的に切るより、検索結果が「読める、直せる、引用できる」code unit を指しやすい。
local-first が中心の境界
CodeRAG は default で fastembed の local ONNX embedding model を使う。API key は不要で、code を外部 service に送る必要もない。README では OpenAI、Anthropic、自前の OpenAI-compatible server、Ollama、vLLM、LM Studio、LocalAI などの backend も扱えるが、それらは optional だ。基本姿勢は、index と retrieval をまず手元に置くことにある。
これは private codebase では大きい。多くの team は agent に code を探させたいが、repository 全体を remote SaaS に渡したくはない。CodeRAG が security governance をすべて解決するわけではないが、少なくとも基本の検索経路は local に動く。index は default で watched directory の .coderag/ に置かれ、file changes は watcher で incremental update され、content hash により duplicate embedding を避ける。
storage layer は LanceDB だ。小さい repository では brute-force search、大きくなると ANN index を自動で作り、large codebase でも query speed を保つ方向になっている。README は 100k+ chunks の規模にも触れており、demo repo だけを想定した tool ではないことが分かる。
agent 向け surface が揃っている
CodeRAG は複数の surface を持つ。CLI、Python library、HTTP/REST、server-rendered Web UI、そして MCP server だ。CLI では coderag index、coderag search、coderag watch、coderag serve、coderag ui、coderag mcp を使える。Python library は自作 tool に組み込める。HTTP service は team が一つの local または internal index を共有する用途に向く。Web UI は人間が search result と file snippets を確認する入口になる。
Gumi 的に特に面白いのは MCP だ。README の位置づけは明確で、Claude Code や Codex のような agent に search_code、search_files、get_file、index_status、reindex を提供し、反復的な shell search の代わりに warm index を使わせる。coderag install は Claude Code、Hermes、Codex の config へ MCP server を登録でき、preview と backup もあるため、手作業の設定を減らせる。
この種類の tool の価値は、「agent が code を読まなくてよくなる」ことではない。むしろ、agent が読むべき code に早く届くことだ。最終判断には file read、diff、tests、review が必要だが、search stage の迷子が減れば task 全体は安定する。
注意したいところ
第一に、project にはまだ release/tag がない。GitHub latest release endpoint は 404、tags API は empty array だった。README は充実しているが、team workflow で version を固定するなら、commit pinning や packaging policy を自分で決める必要がある。成熟した release cadence にはまだ頼れない。
第二に、install path は developer tool 寄りだ。README は venv、editable install、pipx、optional extras を案内している。Python user には自然だが、安定した single binary だけが欲しい人には少し手間がある。HTTP と Web UI もあるが、基本的には local Python environment を理解して使う tool だ。
第三に、README の eval は参考になるが、すべての repository での保証ではない。project 付属 dataset で hybrid retrieval の MRR、R@1、R@5、Hit@10 などを示し、coderag eval で自分でも測れるようになっている。実運用では、自分の codebase と query set で一度測るべきだ。default weight がどこでも最適とは限らない。
第四に、HTTP API は default で unauthenticated だ。README は /file endpoint が indexed source と file contents を読めると明記している。local use では 127.0.0.1 に閉じ、network に出すなら API key、TLS、authentication proxy を用意する必要がある。
まとめ
CodeRAG を記録したい理由は、「agent が code を探す」作業を一時的な shell search から reusable local index layer に変えているからだ。RAG を魔法のように見せるのではなく、hybrid retrieval、symbol-aware chunks、incremental indexing、MCP tools、path:line citations、self-testable eval harness という具体的な engineering problem に落としている。
codebase が大きくなり、grep loop が agent の時間を食い始めているなら、あるいは private repository の検索能力を手元に残したいなら、Neverdecel/CodeRAG は試す価値がある。まだ若く、formal release もないが、方向ははっきりしている。agent が推測を減らし、local index から証拠を取れるようにする tool だ。