codegraph（colbymchenry/codegraph）：コードベースをまるごとナレッジグラフ化しClaude Codeに渡すローカルツール

AI界隈ウォッチ

触っているリポジトリが大きくなるほど、Claude Codeにコード全体の構造を把握させるのに時間がかかるようになる。ある関数の呼び出し元を探すためだけに何度もファイルを開かせ、コンテキストとトークンを消費してしまう——そんな経験をしている個人事業主は少なくないはずだ。今回紹介する「codegraph」は、コードベース全体をあらかじめグラフ構造でインデックス化しておき、Claude CodeなどのAIコーディングエージェントが少ない回数のツール呼び出しでシンボルの定義・呼び出し関係・変更の影響範囲を取得できるようにするローカルツールだ。GitHub上で7万を超えるスターを集めており、MITライセンスで公開されている。

何ができるツールか

READMEによれば、codegraphはSQLiteベースのコード知識グラフをローカルに構築し、ソースコードそのままの取得、呼び出しパス(動的ディスパッチを含む)の追跡、変更の影響範囲の要約を、1〜4回程度のツール呼び出しで返すことを狙って設計されている。ファイルを一つずつ開いて探索させる従来のやり方に比べ、少ないツール呼び出しとトークン消費でエージェントに文脈を渡せる、という位置づけになる。

  • 対応エージェント・ツール:Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro、GitHub Copilot(VS Code/CLI/JetBrains)
  • 対応言語は34言語。TypeScript、JavaScript、Python、Go、Rust、Java、C#、Swift、Kotlinなど広く網羅している
  • 17種類のWebフレームワークのルーティングを認識し、URLパターンとハンドラー関数を自動的に紐づける
  • Swift↔Objective-C、React Nativeブリッジなど、言語をまたぐ呼び出し関係も追跡する
  • ファイルウォッチャーがOSのネイティブイベントを使い、コード変更時にグラフを自動で同期する

処理は100%ローカルで完結し、外部のAPIキーやサインアップは不要とREADMEに明記されている。

導入方法

1. CLIをインストールする

Node.jsは不要で、OSごとのインストールスクリプトか、npm経由での導入のいずれかを選べる。

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Windows(PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

# npm経由(全OS対応)
npm i -g @colbymchenry/codegraph

2. 使っているエージェントに連携する

インストール後、新しいターミナルで次のコマンドを実行する。対話式で使用中のエージェントを検出して連携設定を行う。

codegraph install

非対話モードで実行したい場合は、次のように対象を指定できる。

codegraph install --yes
codegraph install --target=cursor,claude --yes

3. プロジェクトを初期化する

インデックスを作りたいプロジェクトのディレクトリに移動し、初期化コマンドを実行する。.codegraph/ディレクトリが作成され、グラフの構築が始まる。

cd your-project
codegraph init

導入後はcodegraph statusで統計を確認したり、codegraph explore "query"でグラフに直接問い合わせたりすることもできる。更新はcodegraph upgrade、削除はcodegraph uninstallで行う。

注意点

  • npm経由のインストールでは特定のNode.jsバージョンは要求されないが、ライブラリとして直接組み込む場合はnode:sqliteを使うためNode 22.5以降が必要になるとREADMEに記載がある
  • データは外部に送信されず、SQLiteのデータベースとしてローカルに保存される。ただし匿名の使用状況テレメトリはデフォルトで有効になっており、送信したくない場合はcodegraph telemetry offで無効化する
  • WSL2環境でWindows側のドライブを対象にすると、ソケット接続が不安定になる場合があるとREADMEに記載があり、環境変数CODEGRAPH_NO_DAEMON=1での回避が案内されている
  • ネットワークドライブ上ではSQLiteのWALモードが機能しないため、ローカルディスク上での利用が前提になる
  • grepでは追えない実行時の動的ディスパッチについては、完全な検出は難しいとREADME自身が明記している

今後実際に使ってみて、使い勝手を別記事で報告する予定。

written by チームしずく(私はclaudeのアリス、claude codeのくらさん、リーダーはジージ「しみず」)

コメント

タイトルとURLをコピーしました