CodeSage：coding agent に query できる code map を渡す
AI coding agent が時間を失いやすいのは、一行の code を書けない場面ではなく、作業を始めるたびに project を読み直す場面だ。この symbol はどこで定義されているのか。誰が呼んでいるのか。この file を変えると、どの path に影響が出るのか。どの test を一緒に走らせるべきなのか。人間の maintainer には古い地図が頭の中にあるが、agent には今読んだ context window しかないことが多い。
今日見るのは iliaal/codesage。これは、その地図を local tool として作る project だ。tree-sitter で構造 index を作り、embedding と reranker で natural-language search を提供し、CLI と MCP から Claude Code、Codex、Cursor などの agent に渡す。Editor を置き換えるものではなく、agent が変更前により engineering らしい質問をできるようにするものだ。
GitHub repository API、README、Cargo.toml、release API、tags、latest commit、LICENSE を 2026-09-03 18:03 Asia/Shanghai 時点で確認すると、iliaal/codesage は 20 stars、3 forks。主要言語は Rust、license は MIT、default branch は master、repository 作成日は 2026-04-15 19:22:21 UTC、latest push は 2026-09-02 19:53:32 UTC。最新 commit は 1542eb8、commit time は 2026-09-02 19:50:48 UTC、message は release: v0.23.0。最新 GitHub Release は v0.23.0、published time は 2026-09-02 19:51:06 UTC。Cargo.toml の workspace version も 0.23.0 だ。
プロジェクト概要
| 項目 | 内容 |
|---|---|
| リポジトリ | iliaal/codesage |
| 位置づけ | AI coding agent 向け local code intelligence engine。構造 query、semantic search、MCP を提供 |
| Stars | 20 |
| Forks | 3 |
| 主要言語 | Rust |
| ライセンス | MIT |
| 作成日 | 2026-04-15 19:22:21 UTC |
| Latest push | 2026-09-02 19:53:32 UTC |
| 最新 commit | 1542eb8、2026-09-02 19:50:48 UTC、release: v0.23.0 |
| 最新 Release | v0.23.0、2026-09-02 19:51:06 UTC |
| 対応言語 | PHP、Python、C、C++、Java、Rust、JavaScript、TypeScript、Go |
| キーワード | code intelligence、semantic search、tree-sitter、MCP、risk analysis |
agent の最初の迷子時間を減らす
多くの agent session は似た手順で始まる。File name を探す。Keyword を grep する。関係ありそうな file をいくつか開く。Call chain を推測する。それから変更を始める。この流れは動くが、context gathering のコストを token budget に押し込みすぎるし、string match が浅いせいで本当の入口を見落とすこともある。
CodeSage の考え方は、project を query できる local state として先に index しておくことだ。README にある機能は、natural language で code を探すこと、名前から symbol definition を引くこと、references を追うこと、file dependency を見ること、change impact analysis、LLM 用 context bundle の export、git churn / co-change / risk score、そして framework routing や build manifest から behavior-keyed feature slices を作ることまで含む。
この種の tool の価値は、agent が「repository 全体を context に入れようとする」動きを減らすところにある。たとえば authentication flow を変えるなら、まず “authentication handler” で探し、具体的な symbol の callers/callees を確認し、最後に対象 file の blast radius と推奨 test を聞く。返ってくるのは、あいまいな text fragment の山ではなく、構造化された入口だ。
構造 graph と semantic search を一つにする
Semantic search だけだと、「意味は近いが call path にはいない」file を拾いやすい。AST / symbol graph だけだと、そもそもどの名前を query すべきか分かっていないと使いにくい。CodeSage はこの二つを同じ tool に入れている。Natural-language query は problem から code へ入るのに向き、structural query は boundary と impact を確認するのに向く。
README の capability table はかなり実務寄りだ。project_overview は初回の project orientation を出し、find_symbol と find_references は symbol-level location を扱う。list_dependencies は file の import / imported-by を見る。impact_analysis は変更影響を追い、assess_risk と assess_risk_diff は churn、coupling、test gap、trust boundary などの signal で risk を評価する。recommend_tests は changed file に対する test を出し、review_rehearsal は commit 前に reviewer が突きそうな点を予測する。
Agent にとって、これらは孤立した command ではなく一連の loop になるべきだ。入口を見つける。Call relation を確認する。Context を絞る。どの test を走らせるか決める。CodeSage の MCP interface は、その loop を agent tool call の中で直接回すためのものだ。
local 実行の trade-off
CodeSage の README は local deployment を強調している。Rust binary 一つと、各 project の .codesage/ SQLite database。Docker、外部 vector DB、embedding service、systemd service は要求しない。MCP 側は stdio shim で、user-local Unix socket daemon を起動または再利用し、複数の agent session が同じ project cache、embedding model pool、reranker pool を共有できる。
これは個人 project や、余計な infrastructure を増やしたくない小さな team には扱いやすい。Repository の横に index を持ち、agent は local state に query できる。ただし、この選択には現実的な制約もある。Semantic search は model file と ONNX Runtime を扱う。Linux で CUDA acceleration を使うなら nvidia-*-cu12 pip packages が必要になり、Apple Silicon では CoreML の設定を使う。
Security boundary も過信しない方がいい。README は daemon を same-UID co-trust boundary と説明しており、isolation boundary ではない。同じ Unix user の process は onboarded project の index にアクセスできる、という理解が必要だ。Untrusted agent を動かすなら、local daemon を sandbox と見なすのではなく、Unix user や実行環境を分けるべきだ。
v0.23.0 は index の信頼性を詰めている
最新 release v0.23.0 の変更はかなり集中している。index と search が resident daemon session 経由で embedding し、CUDA context の重複 load を減らす。Live watcher は保存が連続した後に dirty file を batch 処理する。No-change incremental index は model を load しない。Semantic fingerprint は ONNX Runtime、model artifacts、pooling、execution provider などを含む。
派手な機能ではないが、この種類の tool では重要だ。Code index が失敗する典型は二つある。Query が重すぎて user が使わなくなること。もう一つは index が stale なのに、tool が確定的な答えのように返してしまうことだ。v0.23.0 は fingerprint、stale detection、retry、watcher stop/restart、hook skip stamp に多くの説明を割いている。長く project の横で動かす tool としての地味な問題を見ている。
README の benchmark の書き方も好感が持てる。まとめた総合点ではなく、semble corpus のうち対応 9 言語・663 query で言語別 NDCG@10 を示し、range は 0.68 から 0.93 だと説明している。さらに、古い benchmark を取り下げた理由や、異なる repo set を pooled number にしてはいけない理由も書いている。Tool 作者として、この抑制はきれいな数字より信頼できる。
向いている人
一つ目は、coding agent で中規模以上の repository をよく変更している人だ。必要なのは、より会話が上手い agent ではなく、無駄に file を読まず、boundary を早く見つけ、どの test が関係するかを説明できる agent かもしれない。
二つ目は、多言語 project の maintainer だ。CodeSage は現時点で PHP、Python、C、C++、Java、Rust、JavaScript、TypeScript、Go に対応している。全言語ではないが、多くの backend、CLI、web service、polyglot repo には十分届く。
三つ目は、review を前倒ししたい人だ。risk-diff、tests-for、review_rehearsal の価値は reviewer を置き換えることではない。Agent が commit 前に「ここで一番壊れそうなのはどこか」を一度答えるようにすることだ。
Caveats
第一に、project はまだ若く、stars も 20 だ。活発で release も多いが、多くの team に揉まれた mature infrastructure ではない。重要な repository に入れる前に、index を捨てても困らず、build が再現できる project で試すのがよい。
第二に、semantic capability は無料ではない。README の設計目標は local run だが、embedding、reranking、model cache、CUDA/CoreML configuration は machine environment に左右される。Symbol lookup だけが必要な場面では、cost が高く見えるかもしれない。
第三に、これは read-only code intelligence であり、symbol rename、move、自動 rewrite はしない。README でも symbol-level edits は未対応で、Serena や editor と組み合わせるものだと書いている。この boundary は健全だが、使う側は navigation と判断の tool として扱うべきで、refactoring engine ではない。
第四に、対応言語はまだ限られる。README では cross-repo queries も未対応で、現在は single-project routing だと説明されている。大型 monorepo や複数 repo の system 全体をそのまま global dependency graph として扱うには、まだ先の機能を待つ必要がある。
まとめ
iliaal/codesage は、agent development のかなり具体的な問題を扱っている。Model は code を書ける。しかし、信頼でき、繰り返し query でき、risk を示す project map が必要だ。CodeSage は semantic search、tree-sitter の構造 query、git history signal、MCP を local tool にまとめ、agent がまず定位し、それから変更し、最後に影響を確認できるようにする。
まだ early project だが、方向は追う価値がある。特に v0.23.0 のように watcher、fingerprint、stale index、no-change index performance に寄った release は、demo feature を積むだけではなく、「code intelligence engine を local で長く動かすと何が問題になるか」を処理していることを示している。すでに agent に real code を変更させているなら、CodeSage は一つの repository で試す価値がある。
プロジェクトアドレス：https://github.com/iliaal/codesage