repo2graph

リポジトリに質問すると、その回答となるソースが返されます。各ブロックの先頭には [cite: path:start-end] が付き、回答全体はツールが適用するトークン上限内に収まります。 1 回の tree-sitter パスで、呼び出し元と呼び出し先、インポートされるもの、git で一緒に 変更され続けているファイルを記録します。検索は BM25 の一致箇所から始まり、こうしたリンクをたどります。

モデルも API キーも言語サーバーもデータベースも必要ありません。ビルド、クエリ実行、 MCP サーバーはいずれもネットワーク接続を行いません。例外は rag --answer（オプトインで パックを LLM に送信）、repo2graph github、GitHub 仕様を指定した rag／query ターゲット （どちらもリポジトリをクローン）、および --vectors／embed（初回使用時に埋め込みモデルを ダウンロード）です。パーサーもこの約束の一部です。 tree-sitter-language-pack は 1.0 未満に固定されているため、すべての文法は初回の パース時にダウンロードされるのではなく、インストール済みの wheel にコンパイルされた状態で 含まれます。詳しくは SECURITY.md をご覧ください。CLI、 Claude Code または Cursor の MCP サーバー、あるいは GitHub Action として使用できます。

試してみる

uvx repo2graph demo                                   # bundled example repo, five questions answered
uvx repo2graph build . -o .r2g                        # index your own code
uvx repo2graph rag "how does routing work" -o .r2g    # a cited, budget-bounded context pack

MCP 経由で、エージェントに同じ機能を使わせることもできます。

claude mcp add repo2graph -- uvx --from "repo2graph[mcp]" repo2graph-mcp .

Cursor、Claude Desktop、その他のクライアントについては、docs/mcp.md をご覧ください。 期待される出力を含む手順については、docs/cli.md の demo をご覧ください。 よく知られた 13 のリポジトリ（Django、FastAPI、React、Kubernetes、Linux など）での出力と、 再現用コマンドを、固定されたコミットとともに掲載しています：examples/。

VS Code では、editors/vscode/ の拡張機能（プレビュー版、ソースからビルド） を使うと、同じ MCP サーバーを通じて、カーソル位置のシンボルの呼び出し元、呼び出し先、 基底クラス、共同変更されたファイルを確認できます。

grep より優れていますか？

ファイルをまたぐ構造に関する質問では、はい。単一ファイル内の字句検索では、いいえ。grep のほうが優れています。 両方を、repo2graph が調整に使用していない Flask、requests、FastAPI、Hono に関する 字句検索の質問 40 件と構造に関する質問 40 件で測定し、回答となる定義に照らして採点しました。 すべての検索手法で同じトークン予算を適用しています （手法、全表、分析、生データは results_holdout_final.json）。

repo2graph が優れている点：ファイルをまたぐ構造に関する質問

grep では、依存関係のエッジをたどったり、逆方向の呼び出し閉包を計算したり、 モジュールをまたぐ委譲を追跡したりすることは構造上できません。証拠がファイルをまたぐ グラフのエッジにまたがっていることが明らかな質問での結果は次のとおりです。

予算	repo2graph	字句検索のみ	grep の後、ヒット箇所の周辺を読む
2,000 トークン	29%	24%	14%
4,000 トークン	60%	48%	21%
8,000 トークン	79%	55%	38%

効果を生み出しているのはグラフです。重要なのはこの比較です。展開を無効にした同じ検索手法と 比べると、展開によって +5／+12／+24 pp 上昇します。grep との差は +15／+39／+41 pp で、 予算が増えるほど縮まるのではなく広がります。grep には、どれだけ余裕を与えてもたどるエッジが ないためです。また、どの予算でも grep より少ないトークン数で回答にたどり着きます。平均で 7、7、398 トークン少なくなります。これは、引用付きの定義を返すほうが、すべてのテキストヒット の周辺ウィンドウを返すよりも小さいためです。

grep が優れているケース：単一ファイルに関する字句的な質問

予算	repo2graph	grep、次にヒット箇所の前後を読む
2,000 tokens	17%	28%
4,000 tokens	29%	48%
8,000 tokens	45%	59%

証拠が単一ファイルにある、純粋に字句的な質問では、テキスト検索が grep の最適な使い方であり、この差は実際にあります。−11/−19/−14 pp です。この差はまだ埋められていません。残る原因はランキングではなく、語彙の不一致のようです。「datetime」という質問は「timestamp」と書かれたコードに一致しません。そのため、高密度ベクトルの経路では 8,000 tokens で差が −2 pp まで縮まりますが、BM25 の調整をさらに行っても効果はありません。この経路にはダウンロードしたモデルが必要なため、オプトイン方式です（pip install "repo2graph[rag]"）。依存関係ゼロのデフォルトは、引き続きデフォルトのままです。この追加機能は PyTorch を導入し、Linux では NVIDIA CUDA のホイールもインストールされます（数 GB）。モデルは初回使用時に Hugging Face から取得されます。導入する前に、モデル自体のライセンスと学習データを確認してください。キャッシュされた後は、HF_HUB_OFFLINE=1 を設定すると、以降の実行ではリクエストが発生しません。

CI ランナーなどでこれを導入するのが負担であれば、pip install "repo2graph[rag-static]" と --embed-backend static を使うと、torch なしで高密度検索を利用できます。model2vec はトークン→ベクトルのテーブルと平均プーリングで構成されているため、推論には numpy を使用し、パッケージは約 60 MB、モデルは約 31 MB です。これは別のモデル（384 次元に対して 256 次元）であり、同じモデルをより安く実行する方法ではありません。そのため、検索結果も異なるものになると考えてください。上記の数値は rag バックエンドのものです。クエリ側でも、embed に使ったものと同じ --embed-backend を指定してください。記録されたモデル ID にはバックエンドごとの接頭辞が付くため、不一致がある場合は、暗黙に融合されるのではなく拒否されます。

エージェントにとっての repo2graph の強み：ターン数の少なさ

シミュレーションしたエージェントのワークフロー（scripts/agent_eval.py を使った search → read → answer）での結果です。ループにモデルは含まれていません。「エージェント」は、実際の ripgrep と実際のインデックスに対する決定論的なポリシーです。

タスクセット	方法	成功率	平均ターン数	平均トークン数	読み取りあたりの適合率
構造的（40）	repo2graph	40%	1.9	2,590	12.0%
構造的（40）	ripgrep	10%	2.5	586	29.0%
字句的（40）	repo2graph	20%	1.4	2,070	21.7%
字句的（40）	ripgrep	18%	3.0	740	89.1%

構造的タスクで成功率は4倍です。また、grep が3ターン必要とする場面でも、1〜2ターンで答えにたどり着きます。最も大きく改善したのはターン数です。構造的タスクでは3.1から1.9になりました。シードのランキングがより正確になり、最初のパックに答えが含まれる頻度が高まったためです。エージェントにとって、トークンを節約するよりターンを節約するほうが価値があります。低コストではありません。構造的タスクでは grep の4.4倍、字句的タスクでは2.8倍のトークンを使い、どちらのタスクでも読み取りあたりの適合率は grep が上回ります。repo2graph はコンテキストを使って再現率とターン数を向上させます。予算をそろえた比較については、上記の単発クエリの表をご覧ください。

参考までに、このページで以前報告していた35＋10問のセット（表の初版から掲載されているため、証拠ではなくリグレッションテスト用のセット）の結果は、字句的タスクで repo2graph が44/63/80%、grep が35/61/72%、構造的タスクで repo2graph が60/80/100%、grep が20/20/70%です。こちらのほうが見栄えのする数値です。だからこそ、上で引用しているのはホールドアウトセットの結果です。

grep にはない機能は次のとおりです。

• 1ホップで関係を取得できます。 repo_neighbours は、シンボルの呼び出し元、呼び出し先、基底クラス、定義ファイルを、それぞれ行番号付きで返します。各エッジには confidence が付与されます。複数の定義を指す可能性のある名前は ambiguous とマークされ、推測で決めつけるのではなく、信頼度は 1/n として評価されます。
• 厳格な上限があります。 パックは返却前に計測され、上限内に収められてから再計測されます（MCP 経由で最大12kトークン）。そのため、このツールによってエージェント自身のコンテキストがあふれることはありません。
• グラフから依存関係をたどれます。 repo_blast_radius は、シンボルに依存する要素を、ホップ数と訪問上限を設けてたどります。各エッジには引用情報が付いています。

Serena、Aider の repo map、CodeGraphContext、code-graph-rag、Sourcegraph、Cursor のインデックス、Claude Code 独自の検索、そして Madge、dependency-cruiser、CodeSee などの依存関係グラフツールとの比較や、それらを代わりに使うべき場合については、docs/comparison.md をご覧ください。Sourcetrail の代替ツールをお探しですか？完全な置き換えではありません。インタラクティブなデスクトップ UI はありません。代わりにできることについては比較ページをご覧ください。

まずは5つの質問から

リポジトリへの質問	グラフで得られる情報
認証はどこで強制されていますか？	ガード本体と、それを呼び出すルート（--framework-edges を指定すると各エンドポイントの名前が表示されます）
<function> を呼び出しているのは何ですか？	その関数に向かう CALLS エッジと、それぞれの信頼度スコア
<module> をカバーするテストは何ですか？	テストモジュールからテスト対象のコードへ向かう IMPORTS エッジ
<api> を変更すると何に影響しますか？	定義と、CALLS エッジからたどれる直接の呼び出し元（説明ノード）
<リクエスト> をルートから永続化まで追跡してください。	ハンドラーとその呼び出し先を1ホップずつたどり、各ブロックにファイルと行番号の引用が付きます

GitHub Action

- uses: actions/checkout@v4
  with: { fetch-depth: 0 }   # full history, so CO_CHANGE edges are meaningful

- uses: Srinivasan-78/repo2graph@v4
  with:
    git-history: "500"
    commit-branch: graph     # optional: publish graph.html to a browsable branch

@v4 はすべての4.xリリースに追従します。手動でアップグレードする場合は、正確なタグ（@v4.1.0）を指定してください。この Action は LLM を呼び出しません。入力と出力についてはdocs/cli.mdをご覧ください。

コマンド

コマンド	内容
repo2graph build <path> -o .r2g	リポジトリを解析してグラフとチャンクを作成します（--incremental、--git-history N、--framework-edges）
repo2graph query "<q>" -o .r2g	BM25 検索とグラフの 1 ホップ検索を行います
repo2graph rag "<q>" -o .r2g	予算内に収まる引用付きコンテキストパックを作成します（--answer を指定すると LLM に送信します。オプトインで、コードを外部に送信する唯一の方法です）
repo2graph explain <edge|node|retrieval>	エッジが存在する理由、またはブロックが検索された理由を説明します
repo2graph github <owner/repo> -o <dir>	ローカルにクローンせずに取得、ビルド、クリーンアップを行います
repo2graph demo	同梱のサンプルにインデックスを作成し、上記の 5 つの質問に回答します
repo2graph map、repo2graph stats、repo2graph index-status、repo2graph embed	graph.html を再レンダリングし、件数と最新状態を報告して、オプションの高密度ベクトルを追加します
repo2graph diff	2 つのビルド間で構造的に何が変わったかを示します。追加、削除、名前変更されたシンボル、エッジ、呼び出し元に変更があった対象を確認できます
repo2graph doctor、repo2graph bug-report、repo2graph explain-path、repo2graph completion	セットアップを診断し、プライバシーに配慮したバグ報告用バンドルを作成し、パスがインデックスに含まれる（または含まれない）理由を説明して、シェル補完を提供します
repo2graph-mcp <path>	stdio MCP サーバー：repo_map、repo_search、repo_neighbours、repo_blast_radius など 5 つのツール

すべてのフラグ：docs/cli.md。Python API：docs/python-api.md。 最大 50,000 ファイルのビルドコスト：benchmarks/perf/README.md。

できないこと

• 型による呼び出しの解決。 呼び出しは名前で照合し、クラス、ファイル、インポート、ディレクトリの範囲で絞り込みます。型が不明なレシーバーに対する x.get() は、事実ではなく、信頼度の低い推測として記録されます。正確な参照が必要な場合は、言語サーバーツールを使用するか、SCIP インデックス（scip-python、scip-typescript など）を build --scip index.scip に渡してください。これにより、インデックスが網羅する呼び出しと基底クラスが正確になります。詳しくはdocs/architecture.mdをご覧ください。
• 動的ディスパッチ、リフレクション、計算されたインポートの検出。 エッジがないからといって、呼び出しが存在しないとは限りません。
• 言語の境界を越えた処理。 （Python からバインディング経由で C++ を呼び出す場合など）
• 呼び出しによって登録されるルートの検出。 build --framework-edges は、デコレーターで宣言されたルートをハンドラーにリンクし（FastAPI、Flask、Starlette、Sanic、NestJS）、エンドポイントごとにノードを追加するため、GET /users/{id} を対象に質問できます。一方、Express、Hono、Django の urlpatterns は app.get("/x", handler) のように呼び出しで登録します。この場合、ハンドラーは引数であり、多くの場合インライン関数であるため、エッジは作成されません。

Python、JS、TS、TSX、Go、Rust、Java、Ruby、C、C++、C#、PHP、Kotlin、Swift、Scala、Bash、Lua、Objective-C、HCL（Terraform）のシンボル、呼び出し、クラスを抽出します。また、Vue と Svelte のコンポーネント内の <script> ブロックや、Jupyter ノートブックのコードセルも対象です。それ以外のファイルもすべてテキストとしてインデックスに登録されます。リフレクションによるディスパッチ、文字列キーを使ったレジストリ、バレルからの再エクスポートなど、解析を妨げる具体的なケースは合成回帰テストスイートで既知の失敗として固定されており、言語ごとの網羅率はdocs/architecture.md §4でスコア化されていますが、均一ではありません。

この 19 言語のうち、実際のリポジトリでベンチマークを行っているのは 2 つです：Python（Flask、requests、FastAPI）と TypeScript（Hono）です。それ以外は、解析済みですが測定されていないものとして扱ってください。これは形式的な話ではありません。検索ベンチマークでは、唯一の TypeScript リポジトリを調べ始めてすぐに、2 つの解析漏れが見つかりました。そのうち 1 つはHono の公開 API 全体を隠しており、どちらも実際のリポジトリに質問してみなければ見つからなかったでしょう。

ステータス

3.x の CLI、MCP ツール、出力スキーマはセマンティックバージョニングに従っています。デフォルトのパスはローカルで実行され、テレメトリーを送信せず、エージェントへの返信からシークレットを常に除外します（マシンから外部に送信されない情報、認証情報ファイルが除外される仕組み、脆弱性の報告）。読み取り専用で、非 root のローカルビルド向けの Dockerfile を提供しています（.github/SECURITY.md）。

プラットフォームと環境の要件

環境	ステータス	詳細
Python	3.10 – 3.14	CI で Linux、macOS、Windows を対象にテスト済みです（15 セル）。Python 3.15 以降は未テストです。なお、3.10 は 2026 年 10 月にサポート終了となりました。引き続きサポート対象の最低バージョンですが、アップグレードを推奨します。
Linux (glibc)	サポート対象（glibc ≥ 2.34）	事前コンパイル済みの tree-sitter-language-pack 文法ホイールには glibc ≥ 2.34 が必要です（Ubuntu 22.04 以降、Debian 12 以降、RHEL 9 以降、Amazon Linux 2023 以降）。
旧バージョンの Linux	ホイールは非対応	RHEL 8、CentOS 8、Amazon Linux 2、Debian 11、Ubuntu 20.04 には glibc < 2.34 が付属しています。ホイールを読み込めないため、glibc 2.34 以降のコンテナを使用するか、ソースから文法をコンパイルしてください。
Alpine / musl	ホイールは非対応	musl libc 向けの事前コンパイル済み文法ホイールは配布されていません。glibc コンテナを使用するか、C ツールチェーンでビルドしてください。
macOS / Windows	完全サポート	macOS 12 以降（Apple Silicon と Intel）および Windows 10/11（UTF-8 と CP1252 のコードページ）でテスト済みです。

環境とプラットフォームのサポート状況を診断するには、repo2graph doctor を実行してください。

セキュリティとメンテナンスの方針

• 単独メンテナー： repo2graph は、単独の作者（@Srinivasan-78）が開発・メンテナンスしています。
• 自動チェック： プルリクエストは、自動 CI チェック（ruff、mypy、複数 OS のテストマトリックス、合成回帰ベンチマーク）に合格する必要があります。
• レビュー方針： プルリクエストを main にマージする際、サードパーティによるレビュー承認は 0 件で構いません。
• コミット署名： 現在、main ではコミット署名を必須としていません。
• 完全性： リリースは来歴証明とともに PyPI で公開されます。CI とコントリビューター向けに、uv.lock ではすべての依存関係をハッシュで固定しています（uv sync --frozen）。通常の pip install repo2graph は pyproject.toml に記載された範囲内で独自にバージョンを解決し、同ファイルを読み込みません。

コントリビューション

git clone https://github.com/Srinivasan-78/repo2graph && cd repo2graph
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
make lint format-check typecheck test

develop からブランチを作成してください。.github/CONTRIBUTING.md と docs/architecture.md から始めてください。現時点で最も役立つコントリビューションは、 検索ベンチマーク向けの新しい質問です。特に、詳しいリポジトリに関する質問を歓迎します。ドキュメント一覧：アーキテクチャ、CLI、 MCP、Python API、比較。

MIT ライセンスです。