codegraph - AI coding agent にローカルなコード地図を渡す

AI coding agent は、だんだん新しい同僚のような存在になっています。Code を変更し、command を実行し、test も書けます。ただし、最初に渡される情報が散らばった file だけだと、人間の新人と同じように構造を誤解します。まず grep して、大きな file をいくつか読み、そこから function の呼び出し範囲を推測する。小さな project なら十分でも、中規模の codebase では、一つの helper の境界を読み違えるだけで、その影響が code review や CI まで残ります。

今日紹介する optave/ops-codegraph-tool は、この問題に向けた local code graph tool です。npm package 名は @optave/codegraph。codegraph CLI と MCP server を提供し、codebase を function-level dependency graph として解析します。AI agent や developer は、変更前に「この symbol はどこにあるか」「誰が呼んでいるか」「どの function に影響するか」を問い合わせられます。GitHub search result では現在およそ 64 stars、12 forks。主な言語は TypeScript と Rust、license は Apache-2.0 です。npm の latest version は 3.11.1 と表示されています。

プロジェクト概要

項目	内容
リポジトリ	optave/ops-codegraph-tool
npm package	@optave/codegraph
Stars	約 64
Forks	12
主な言語	TypeScript、Rust
ライセンス	Apache-2.0
現在の version	v3.11.1

解いているのは構造 context の問題

一般的な AI coding workflow で agent が足りないのは、「code を書く能力」だけではありません。むしろ重要なのは、書く前に code structure を理解しているかどうかです。一つの file だけを読むと、ある function に十数個の upstream caller があることを見落とします。安全のために関連 file を全部読むと、今度は context window をすぐ消費します。

codegraph は、この structural information を事前に index する方針です。README によると、tree-sitter で code を parse し、function、call、import、export、role、complexity、control flow、data flow などの情報を local SQLite database に保存します。Agent が context を必要としたとき、二十回の grep、find、cat を繰り返す代わりに、graph database に直接聞けます。

この tool の価値は type system や test の置き換えではありません。Blind edit を減らすことです。たとえば parseConfig を変更する前に、それがどこにあり、何を呼び、誰から呼ばれ、変更がどこへ伝わるのかを確認できます。AI agent にとっては、source code の一部だけを prompt に入れるより、実際の engineering judgment に近い情報になります。

CLI と MCP の二つの入口

codegraph は人間と agent の両方を想定しています。Developer は CLI を直接使えます。

npm install -g @optave/codegraph
cd your-project
codegraph build
codegraph where handleAuth
codegraph context handleAuth -T
codegraph diff-impact --staged -T

これらの command は、symbol location、function context、call chain、file dependency、change impact、cycle detection、complexity check などの高頻度操作をカバーします。

AI agent にとって重要なのは MCP server です。

codegraph mcp

README では、三十個以上の MCP tools を提供すると説明されています。Claude Code、Cursor、その他 MCP 対応の coding agent は、filesystem を毎回読みに行くのではなく、local code graph を直接 query できます。Default の single-repo mode は現在 project の .codegraph/graph.db だけを扱い、multi-repo access は明示的に有効化します。この default boundary はかなり重要です。

Function-level impact analysis が細かい

多くの code browsing tool は「この file が何を import しているか」を教えてくれます。codegraph はさらに function-level relationship に寄せています。ある function が何を呼ぶのか、誰がその function を呼ぶのか、変更したときにどの upstream node へ伝わるのかを見ます。

Refactor ではこの粒度が効きます。File-level dependency graph は、大きな module では粗すぎます。Utility file に数十個の function がある場合、そのうち一つだけを変えるなら、file 全体の importer をすべて同じ risk として扱う必要はありません。Function-level graph があれば、影響範囲を具体的な symbol に縮められます。

README には role classification もあります。Symbol を entry、core、utility、adapter、dead、leaf などに分類します。これは agent への risk hint として使いやすい設計です。同じ一行変更でも、leaf function を変えるのと high fan-in の core function を変えるのでは、review の仕方が違うべきだからです。

Diff impact は commit 前に向いている

codegraph で一番試しやすい場面は、commit 前の確認だと思います。diff-impact は現在の git diff を解析し、変更が重なった function を見つけ、その caller と影響範囲をたどります。

これは人間にも useful ですが、AI agent には特に効きます。多くの agent は「test が通るように code を直す」ことはできますが、「今回の変更の blast radius はどれくらいか」を自動で聞くとは限りません。codegraph diff-impact --staged -T を agent instruction や hook に入れておけば、commit 前に structural reminder を得られます。

README では GitHub Actions の利用例も示されています。PR に impact analysis comment を出したり、影響 function 数が threshold を超えたときに fail したりできます。Traditional lint ではなく、structure risk を CI が扱える signal にする発想です。

Multi-language と local-first

codegraph の README は 34 languages support を掲げています。JavaScript、TypeScript、Python、Go、Rust、Java、C#、PHP、Ruby、C/C++、Kotlin、Swift、Scala、Bash、HCL、Elixir、Lua、Dart、Zig などを含みます。Multi-language monorepo では、一つの language に閉じた tool よりも統一しやすいはずです。

Implementation は二つの parse path を持っています。Rust native addon と WASM tree-sitter fallback です。package.json からも、TypeScript の本体、Rust native package、SQLite dependency、optional MCP SDK が見えます。README は local execution、zero telemetry、API key 不要も強調しています。Semantic search や deeper LLM capability は optional です。

この境界は良いです。Code structure indexing は、default で source code を remote service に送るべきではありません。Private repo や company codebase では、まず local SQLite graph を作り、必要なときだけ LLM provider を選ぶ model のほうが受け入れやすいです。

Search だけでなく architecture constraint も扱う

codegraph の feature list はかなり長いです。where、context、query のような navigation commands に加えて、complexity metrics、cycles、co-change analysis、CODEOWNERS integration、architecture boundaries、manifesto rules、triage queue、graph export もあります。

つまり、単なる code search tool ではなく、structure analysis、impact analysis、quality gates を一つにまとめようとしています。たとえば次のような使い方です。

• cycles で circular dependency を探す。
• complexity で function complexity を見る。
• roles --role dead で unused symbol を探す。
• check --staged を CI や pre-commit の pass/fail signal にする。
• owners で CODEOWNERS を symbol level に mapping する。
• plot で interactive graph view を生成する。

Team で採用するなら、最初から全部を有効化する必要はありません。まず build、where、context、fn-impact、diff-impact だけを agent に使わせるのが現実的です。Graph data が安定してから CI gates や boundary rules を足せます。

向いている workflow

codegraph は次のような人にまず試してほしい tool です。

• Claude Code、Codex、Cursor、その他 AI coding agent で実際の codebase を変更している。
• Agent が call relationship を誤読して手戻りすることが多い。
• Codebase が multi-language で、grep や LSP だけでは視点が分散する。
• PR に structure impact を出したいが、lint と test だけでは足りない。
• MCP tool は default local execution にしたい。
• Agent instruction に「変更前は fn-impact、commit 前は diff-impact」のような engineering constraint を入れたい。

Project が小さい場合や、単に function の場所を探すだけなら、LSP、ripgrep、IDE で十分です。codegraph の価値は、codebase が大きくなり、call relationship が深くなり、agent が頻繁に変更へ参加するほど見えやすくなります。

注意したい境界

この種の static analysis tool には必ず限界があります。README でも limitation が明記されています。TypeScript analysis は完全な tsc type check ではありません。Dynamic calls は best-effort です。Python import はすべての sys.path や virtual environment package を追うわけではありません。Dataflow analysis は intraprocedural、つまり function 内の範囲です。

そのため、codegraph を「絶対に正しい call truth」として扱うべきではありません。より正確には、agent と reviewer に十分使える地図を渡し、明らかな impact と structure risk を早く見つける tool です。地図は現場そのものではありませんが、地図がないと agent は局所的な視界だけで動きやすくなります。

また、graph database は新鮮である必要があります。README には watch mode、incremental build、hook examples、CI cache の提案があります。Team workflow に入れるなら、.codegraph/graph.db をいつ rebuild し、いつ cache し、いつ full rebuild するのかを決めておくべきです。古い graph を agent が信じると、逆に誤解を増やします。

まとめ

optave/ops-codegraph-tool は、AI coding 時代にかなり合った niche developer tool です。Agent が毎回ゼロから code structure を探るべきではないし、数回の grep だけで impact を推測するべきでもない、という現実的な問題を扱っています。

Local に function-level dependency graph を作り、それを CLI、MCP server、CI gate、hook から人間と agent に渡す。AI agent を実際の開発に入れ始めた team にとって、このような structure context layer は今後さらに重要になります。codegraph はまだ速く進化している tool ですが、方向は明確です。Agent が手を動かす前に、まず codebase の地図を見せることです。

リポジトリ：https://github.com/optave/ops-codegraph-tool