repo-graph

AIコーディングアシスタントのための構造グラフメモリ。 コードベースをマッピングし、構造に基づいてナビゲートし、重要な部分だけを読み取ります。

repo-graphは、LLMにコードベースの地図（エンティティ、関係性、フロー）を提供します。これにより、LLMはすべてを先に読み込むことなく、適切なファイルへナビゲートできるようになります。

コードベース全体をLLMのコンテキストウィンドウに詰め込んだり（あるいは推測に頼ったり）する代わりに、repo-graphは何が存在し、どのように接続され、どこがエントリポイントなのかを示す軽量なグラフを構築します。LLMはグラフにクエリを投げ、必要な最小限のファイルセットを見つけ出し、それらのみを読み取ります。

デモ

https://github.com/user-attachments/assets/a1e4171b-b225-40d4-9210-39453e14b76a

https://github.com/user-attachments/assets/fc3191e5-fc35-4bd7-8372-72af55995883

同じバグ、同じモデル、同じプロンプトでも、repo-graphがインストールされているかどうかで結果が異なります。

タスク: Go + Angularのモノレポ（566ノード、620エッジ）における逆転した比較演算子の修正。

トークン数は2.5倍削減。速度は約9倍向上。同じ正確な修正。

テストの実行方法

比較を公平に保つため、両方の実行で同一の条件を使用しました：

• 同じモデル: Claude Opus, 100% (Haikuルーティングなし)

• 同じプロンプト: "最近作成されたグループが「閉鎖」と表示され、古いグループが「オープン」と表示されています。これは逆です。新しいグループはメンバーが参加できるように「オープン」であるべきです。バグを見つけて修正してください。"

• クリーンなコンテキスト: 各実行は、以前の会話がない /clear から開始

• 他のツールなし: 両方の実行でCLAUDE.md、プラグイン、フック、その他すべてのMCPサーバーを削除しました。唯一の変数はrepo-graphがインストールされているかどうかのみです

• ヒントなし: プロンプトは症状を説明しているだけで場所は示していません。Claudeは自力で group_controller.go:57 を見つける必要があります

repo-graphなしでは、Claudeはキーワードをgrepし、ファイルを読み込み、再度grepし、さらにファイルを読み込み、最終的にバグを絞り込みます。repo-graphがあれば、Claudeは flow("groups") を呼び出し、正確なハンドラー関数とファイルを取得し、それを読み込んで修正します。

FastAPI, Gin, Hono, NestJS の 事前生成された例 を参照してください。インストール不要で実際のグラフ出力を確認できます。

問題点

コードを扱うLLMは、コンテキストの大部分を方向性の把握に浪費しています：

• 無関係と判明するファイルの読み込み

• 異なる言語間のコンポーネントの接続を見落とす

• 機能がどこから始まり、何に影響するのかが不明

• 5ファイルで済むはずの作業で50ファイルを読み込む

これはコストがかかり、低速であり、コードベースが成長するにつれて悪化します。

repo-graphによる解決策

repo-graphはコードベースを一度スキャンし、以下のグラフを構築します：

• エンティティ: モジュール、パッケージ、クラス、関数、ルート、サービス、コンポーネント

• 関係性: インポート、呼び出し、ハンドリング、定義、包含

• フロー: エントリポイントからデータ層までのエンドツーエンドのパス

そして、LLMが以下のことを行える12のMCPツールを提供します：

1. 方向性の把握 — "このリポジトリにはどんな言語があるか？主な機能は何か？"

2. ナビゲーション — "ルートからデータベースまでのログインフローを追跡する" / "UserServiceと決済APIの最短パスは？"

3. スコープの特定 — "この機能を理解するには何行読む必要があるか？" / "このバグ修正に必要なファイルだけを教えて"

4. 評価 — "この関数を変更した場合の影響範囲は？" / "どのファイルが最大のメンテナンスリスクか？"

LLMは数千行を読み込む代わりに、数百トークンで構造的なコンテキストを得ることができます。

対応言語

複数のアナライザーが1つのリポジトリに一致する場合があります（例：Goバックエンド + Angularフロントエンド + SCSS）。それぞれがノードとエッジを単一の統合グラフに提供します。

インストール

pip install mcp-repo-graph

Python 3.11以上が必要です。唯一のランタイム依存関係は mcp[cli] です。

クイックスタート

1. グラフの生成

repo-graph-generate --repo /path/to/your/project

これによりコードベースがスキャンされ、ターゲットリポジトリ内の .ai/repo-graph/ にグラフデータが書き込まれます。

2. AIアシスタントへの接続

MCP設定に追加します：

Claude Code (~/.claude/claude_code_config.json またはプロジェクトの .mcp.json):

{
  "mcpServers": {
    "repo-graph": {
      "command": "repo-graph",
      "args": ["--repo", "/path/to/your/project"]
    }
  }
}

環境変数を使用する場合:

{
  "mcpServers": {
    "repo-graph": {
      "command": "repo-graph",
      "env": { "REPO_GRAPH_REPO": "/path/to/your/project" }
    }
  }
}

3. 使用方法

AIアシスタントは12個すべてのツールにアクセスできるようになります。回答可能なクエリの例：

• "このコードベースは何をするもの？" -> status ツール

• "チェックアウトフローを追跡して" -> flow ツール

• "UserServiceを変更したら何が壊れる？" -> impact ツール

• "このバグに必要なファイルはどれ？" -> minimal_read ツール

• "このファイルは大きすぎる、どう分割すべき？" -> split_plan ツール

• "認証フローを視覚的に見せて" -> graph_view ツール

4. gitフックで最新の状態に保つ（推奨）

repo-graph-generate をプリコミットフックに追加して、グラフが自動的に最新の状態に保たれるようにします。再生成にLLMのコンテキストを消費することはありません：

# .git/hooks/pre-commit (or add to your existing hook)
#!/bin/sh
repo-graph-generate --repo .
git add .ai/repo-graph/

chmod +x .git/hooks/pre-commit

コミットするたびにグラフが最新になります。LLMは generate にトークンを無駄にすることなく、常に最新の地図を持つことができます。

ヒント: バージョン管理にグラフデータを含めたくない場合は、.gitignore に .ai/repo-graph/ を追加し、git add の行をスキップしてください。グラフはローカルのみに存在します。

MCPツールリファレンス

生成

ナビゲーション

コンテキスト予算管理

健康状態分析

仕組み

1. 検出 — scan_project_dirs() がプロジェクトルート（packages/*, apps/*, services/*, src/* などのモノレポレイアウトを含む）を見つけます。各アナライザーがマーカーファイルを確認します。

2. スキャン — 一致するアナライザーが正規表現ヒューリスティックを使用してエンティティと関係性を抽出します。AST解析や外部ツールチェーン、ビルドステップは不要です。

3. マージ — すべてのアナライザーの結果が単一のグラフにマージされます。ノードはIDで、エッジは (from, to, type) で重複排除されます。

4. 提供 — MCPサーバーがグラフをメモリにロードし、BFSベースのトラバーサルツールを公開します。

グラフデータ形式

生成されたファイルはターゲットリポジトリ内の .ai/repo-graph/ に配置されます：

• nodes.json — [{id, type, name, file_path}, ...]

• edges.json — [{from, to, type}, ...]

• flows/*.yaml — 順序付けられたステップシーケンスを持つ名前付き機能フロー

• state.md — 素早い把握のための人間が読めるスナップショット

エッジタイプ: imports, defines, contains, uses, calls, handles, handled_by, exports, includes。

新しいアナライザーの追加

repo_graph/analyzers/<language>.py を作成します：

from .base import AnalysisResult, Edge, LanguageAnalyzer, Node, scan_project_dirs, rel_path, read_safe

class MyLangAnalyzer(LanguageAnalyzer):

    @staticmethod
    def detect(repo_root):
        # Check for language marker files
        return any(
            (d / "my-marker").exists()
            for d in scan_project_dirs(repo_root)
        )

    def scan(self):
        nodes, edges = [], []
        # ... scan files, extract entities, build relationships ...
        return AnalysisResult(
            nodes=nodes,
            edges=edges,
            state_sections={"MyLang": f"{len(nodes)} entities\n"},
        )

    # Optional: file-level analysis for bloat_report / split_plan
    def supported_extensions(self):
        return {".mylang"}

    def analyze_file(self, file_path):
        # Return dict with function/method sizes, class counts, etc.
        pass

    def format_bloat_report(self, analysis):
        # Format the analysis dict into a human-readable string
        pass

analyzers/__init__.py の _analyzer_classes() に追加して登録します。

ライセンス

MIT

サポート

repo-graphが時間の節約になった場合は、コーヒーを一杯おごることを検討してください。