graph-it-live

Graph-It-Live

コードベース分析のための AI ファーストな依存関係インテリジェンス CLI です。 エージェント対応の IDE または CLI から、依存関係、呼び出しグラフ、シンボル、影響、アーキテクチャを分析します。

使用する場面

• ファイルの依存関係とインポートを分析する
• ファイルをまたいで関数の実行を追跡する
• シンボル（関数、クラス、メソッド）の呼び出し元をすべて見つける
• リファクタリング前に破壊的変更を検出する
• 未使用のエクスポート／デッドコードを見つける
• 任意のファイルのコードマップ（構造の概要）を生成する
• ファイル内の呼び出し階層とロジックの流れを分析する
• エントリーポイントから依存関係ツリー全体をたどる
• 指定したファイルをインポートしているファイルをすべて見つける（逆引き）
• 循環依存関係／循環を検出する
• 関数シグネチャの変更による影響を確認する
• ワークスペースのアーキテクチャ概要を取得する
• Git の差分から、破壊的なシグネチャ、影響、循環、テスト候補を確認する

クイックスタート — インストール

Node.js v22 以降が必要です。

# Install globally
npm install -g @magic5644/graph-it-live

# Or run without installing
npx @magic5644/graph-it-live <command>

グローバルインストール後、graph-it を PATH から利用できます。次のコマンドで確認してください。

graph-it --version

CLI を自動でインストールしないでください。以下の確認ポリシーに従い、確認が取れた場合にのみ更新してください。利用できない場合は、記載されているインストール方法を提示し、明示的な依頼を待ってください。

CLI と機能の確認

セッション中に Graph-It のスキルが初めて有効になったとき、CLI とターミナルが利用可能であれば graph-it --version を確認してください。実行ファイルとターミナルを利用できる場合は CLI を優先してください。CLI が利用できない、または適切でない場合に限り、接続されたホストが同等のツールとスキーマを提示しているとき、MCP をフォールバックとして使用してください。CLI が提供する既存の新バージョン通知があればそれだけを使い、npm を照会したり、別途更新確認を追加したりしないでください。同じセッション内の Graph-It スキル間で、バージョン、ツール一覧、更新の判断を共有し、機能の確認やプロンプトの表示はそれぞれ最大 1 回にしてください。graph-it tool --list でツールを確認してください。必要な場合に限り、graph-it --help またはコマンドのヘルプを参照してください。CLI／バージョン、MCP サーバー、またはワークスペースのコンテキストが変わった場合、あるいは要求されたツールが不明な場合を除き、そのツール一覧を再利用してください。以下の例は参考例であり、固定された機能一覧ではありません。

CLI が新しいバージョンを通知した場合、対話形式で graph-it update を実行する前に、明示的な肯定の確認を求めてください。無応答、タイムアウト、拒否、非 TTY での実行、一般的なエージェントモードは、同意とはみなしません。自動モードが明示的に有効化され、事前に許可されている場合は、更新の判断をデフォルトで「はい」とし、追加の確認なしで graph-it update を実行してください。成功したら、graph-it --version と graph-it tool --list を再確認し、キャッシュされた機能情報を無効化してください。MCP サーバーがすでに動作している場合、更新された CLI を利用するにはホストが再起動を許可する必要があることを伝えてください。更新に失敗した場合、既存の CLI が引き続き利用可能であれば、それだけを使い続けてください。そうでなければ、失敗を説明し、CLI による分析を中止してください。簡潔に警告し、対応をエスカレートしたり、ループ状に再試行したりしないでください。

この手順には Graph-It-Live CLI 1.21.0 以降が必要です（check-architecture、architecture --level units、--matrix、および 24 個の MCP ツール）。最初に有効になった時点で、報告された graph-it --version を 1.21.0 と比較してください。それより古い場合は、その旨を 1 回だけ伝え、利用できないコマンドを示したうえで、上記の確認ポリシーに従った graph-it update を提案してください。更新されるまでは、その CLI の --help と tool --list に記載されたコマンドのみを使用してください。存在しないコマンドの出力を、実行結果として提示してはいけません。バージョンを読み取れない場合も、古いバージョンとして扱ってください。

graph-it tool <name> は、CLI から分析ツールを直接実行するものであり、すべての CLI コマンドを MCP 経由で実行するものではありません。graph-it serve は MCP サーバーを起動します。MCP をフォールバックとして使う場合は、接続されたホストの現在のツールスキーマが提示するツール、名前空間、パラメーターのみを使用してください。CLI の --format と MCP の response_format は別のインターフェースです。後者は、MCP スキーマが対応している場合に限り使用してください。

対応言語

TypeScript、JavaScript、Python、Rust、C#、Go、Java、Vue、Svelte、GraphQL。

CLI コマンドリファレンス

最初にコードベース全体を確認する（エージェントの初期設定）

機能開発、監査、リファクタリング、オンボーディングなど、広範なタスクを開始するときは、このワークフローを使用します。

# 1) Build/refresh the index
graph-it scan

# 2) Generate the agent-optimized global map
graph-it architecture --format toon

この TOON の結果は、エージェントにとっての主要なコンテキストです。nodes、edges、failedFiles、nodeCount、edgeCount が含まれます。

その後に、対象を絞った分析を実行します。

# Illustrative tool names; verify the installed inventory and parameters first
graph-it tool generate_codemap --filePath=/abs/path/to/file.ts
graph-it tool query_call_graph --filePath=/abs/path/to/file.ts --symbolName=mySymbol --depth=3
graph-it explain /abs/path/to/file.ts

自由形式のアーキテクチャに関する質問には、自然言語クエリを使用します。

graph-it query "how does authentication flow through this project"

グローバルグラフが大きすぎる場合：

graph-it architecture --maxFiles 300 --format toon

人間向けの視覚的なオプション（LLM コンテキスト用ではありません）：

graph-it architecture --format mermaid            # flat file graph
graph-it architecture --groups --format mermaid   # one subgraph (or node) per folder group, edges labelled with file-pair counts

厳選した図を作成するには、graph-it architecture --groups --format json を実行し、groups、 groupEdges、context と正確な件数を図解スキル（architecture-diagram、archify）に渡します。役割に関する注記やルールは人間による注釈です。実行時のフローは graph-it trace から取得される静的解析結果であり、実際の実行を観測したものではありません。

グラフ全体を読む代わりに、同じグループを段階的に調べるには、graph-it tool explore_architecture（概要）を呼び出し、続いて --group=<key>（ファイルと境界）、さらに --from=<key> --to=<key>（グループエッジの根拠となるファイルの組。--limit／--offset でページ分割）を指定します。

その他のアーキテクチャレベル（json／toon）：

graph-it architecture --level units --format toon              # packages (else top-level folders), layers, unit edges, cycles
graph-it architecture --folder "(root)/src" --format toon      # one level below a unit or folder key
graph-it architecture --level units --matrix --format toon     # dependency structure matrix (also --format csv)

ワークスペースで graphit.architecture.json にルールが定義されている場合、graph-it check-architecture はすべての静的インポートをルールと照合します。graphit.architecture.baseline.json に記録されていない error 違反があると、終了コード 1 を返します。--update-baseline を指定すると、現在の違反が許容されます。

ワークスペースのインデックスを作成する

分析コマンドを実行する前に scan を実行して、依存関係インデックスを作成します。ほとんどの分析コマンドは、このインデックスに依存します。 例外は review-pr コマンドです。このコマンドは自動的にインデックスを作成するため、別のコマンド用にインデックスを更新する必要がない限り、先に scan を別途実行しないでください。

graph-it scan

重要なファイル変更を行った後は、インデックスを更新するために再実行してください。

ワークスペースのルート。 ワークスペースのルート外に解決されるインポートはスキップされます。--workspace を指定しない場合、CLI は package.json または tsconfig.json を含む最も近いディレクトリを使用します。graph-it -w <dir> は指定どおりのディレクトリを使用し、.graph-it/（インデックス＋キャッシュ）はその場所に作成されます。モノレポで影響範囲、依存先、パッケージ間の関係を調べる場合は、パッケージに cd するのではなく、モノレポのルートを graph-it -w <monorepoRoot> ... に渡してください。scan がインポートの解決先がワークスペースのルート外であると警告した場合、結果の対象はそのルートのみです（get_index_status が outOfRootImports と monorepoRoot を報告します）。表示された --workspace を指定して再実行するか、制限事項を明記してください。

ワークスペースの概要

graph-it summary                   # Full workspace overview
graph-it summary src/api.ts        # Per-file codemap

ファイルごとのコードマップには、エクスポート、内部要素、依存関係、依存先、呼び出しフロー、循環が含まれます。

実行フローを追跡する

関数を起点に、呼び出しチェーン全体を追跡します。

graph-it trace src/index.ts#main
graph-it trace src/auth.ts#validateToken

形式：<filePath>#<functionName>。絶対パスまたは相対パスを使用します。

ファイルのロジックを分析する

ファイル内の呼び出し階層（どの関数が、どの関数を、どの順序で呼び出すか）を表示します。

graph-it explain src/server.ts

エントリーポイント、呼び出しツリー、内部循環が返されます。

依存関係グラフ

エントリーファイルから依存関係ツリー全体をたどります。

graph-it path src/index.ts

推移的なインポートをすべて表示し、循環依存を検出します。

未使用のエクスポートを検出する

デッドコード（他のファイルからインポートされていないエクスポートシンボル）を検出します。

graph-it check src/api.ts

インストール済みのツール一覧に同等のツールがある場合は、ワークスペース全体のデッドコードをスキャンします。

graph-it tool scan_dead_code

呼び出しグラフの関係から Markdown の Wiki を生成します。

graph-it wiki

プルリクエストまたは差分のレビュー

決定論的なローカル差分分析には、専用コマンドを使用します。Git のベース参照が必要で、インデックスは自動的に作成されます。--head を指定しない場合、ベースと現在の作業ツリーを比較します。ステージ済みの内容と未ステージの内容がどちらも対象です。コミット済みのローカルまたはリモートの参照を 2 つ比較するには、--head <ref> を渡します。

graph-it review-pr --base origin/main --format markdown
graph-it review-pr --base origin/main --head feature/my-change --depth 3 --max-files 200 --format toon

マージを推奨する前に、risk、score、limitations、isPartial を確認してください。

• low、medium、high、critical は、変更されたシンボルのうち最も高いリスクを分類します。
• isPartial: true は、ファイル、パーサー、または影響範囲の深さに関する上限により、結果が不完全であることを意味します。
• シグネチャに破壊的変更がないからといって、動作の変更が安全だとは限りません。テストと影響を受ける処理フローを確認してください。

接続先の MCP ホストが、構造的に同等なレビュー用ツールを提示している場合は、その正確な名前と入力スキーマを使用してください。CLI オプションが MCP パラメーターに対応するとは限りません。VS Code Branch Watch の信頼度ラベルは UI のコンテキスト情報であり、CLI の仕様には含まれません。

完全なレビューワークフローと GitHub Actions ゲートについては、pr-review スキルを使用してください。

出力形式

graph-it --help またはコマンドのヘルプで --format が提示されている CLI コマンドの場合：

形式	最適な用途
text	ターミナルで手早く人が読む場合（デフォルト）
json	プログラムによる処理、スクリプト
toon	AI による処理 — JSON と同じデータを 30～60% 少ないトークン数で表現
markdown	構造化された出力をドキュメントに埋め込む場合
mermaid	人が見る視覚的な図 — VS Code、GitHub、Obsidian、または任意の Markdown プレビューでフローチャートとして表示されます。trace と path のみ対応しています。

適切な形式の選び方：

• エージェントまたはスクリプト内で出力を処理する → --format toon
• チャットやプレビューウィンドウで、人にコールグラフや依存関係ツリーを見せる → --format mermaid
• その他すべてのプログラムによる利用 → --format json

graph-it summary src/api.ts --format toon          # AI reads it
graph-it trace src/index.ts#main --format mermaid  # human sees the diagram
graph-it path src/index.ts --format mermaid        # dependency tree as flowchart

ツール呼び出しの例

これらの例は CLI の使用方法を示すものであり、ツールセットを保証するものではありません。ツールやパラメーターを選ぶ前に、インストール済みの一覧と関連するヘルプを確認してください。query_call_graph が利用可能な場合は、呼び出し箇所のクエリに使用してください。ファイル内のロジックには graph-it explain を使用します。MCP では、ホストが提示するツール名／名前空間とスキーマのみを使用してください。graph_context が提示されている場合は、自由形式の質問の出発点として利用できます。公開されているとは限らないため、前提にしないでください。

# Analyze a single file's dependencies
graph-it tool analyze_dependencies --filePath=/abs/path/to/file.ts

# Find all files importing a specific file
graph-it tool find_referencing_files --targetPath=/abs/path/to/file.ts

# Illustrative: query call sites only if this tool and parameters are advertised
graph-it tool query_call_graph --filePath=/abs/path/to/file.ts --symbolName=myFunction --direction=callers --depth=1

# Full impact analysis
graph-it tool get_impact_analysis --filePath=/abs/path/to/file.ts --symbolName=myFunction

# Detect breaking changes (use --args JSON for large content payloads)
graph-it tool analyze_breaking_changes --args '{"filePath":"/abs/path/to/file.ts","symbolName":"myFunction","oldContent":"...old source...","newContent":"...new source..."}'

# Generate codemap
graph-it tool generate_codemap --filePath=/abs/path/to/file.ts

# Illustrative: verify the installed tool's supported parameters first
graph-it tool query_call_graph --filePath=/abs/path/server.ts --symbolName=handleRequest --depth=3

# Workspace-wide dead code scan (across all files, unlike find_unused_symbols which is per-file)
graph-it tool scan_dead_code

# Natural-language architecture question
graph-it query "what calls the MCP worker and how"

# Generate wiki docs from call graph
graph-it wiki --output docs/wiki

CLI ツールのパラメーターについては、インストール済みツールのヘルプ／スキーマに従ってください。そのパラメーターで絶対パスが必要な場合は、絶対パスを使用します。CLI の --format が制御するのは CLI の出力のみです。

重要なルール（絶対に守ること）

• 絶対に graph-it scan の実行前に分析を行わないでください。ただし、インデックスを自動作成する review-pr は例外です。
• 絶対に、例に登場するという理由だけでツール名やパラメーターが存在すると決めつけないでください。現在の CLI の一覧／ヘルプ、または MCP スキーマで確認してください。
• 絶対に、提示された入力スキーマが対応していない CLI フラグや出力設定を MCP に渡さないでください。

MCP サーバーモード

AI クライアントと連携するため、MCP サーバーとして起動します（VS Code は不要です）。

graph-it serve

MCP の利用可否は、接続先ホストが現在提示しているツールと入力スキーマによって決まります。インストール済み CLI の一覧とは異なる場合があります。このドキュメントに記載されたツール名、名前空間、パラメーター、出力オプションを前提にしないでください。response_format は CLI の --format フラグではありません。ホストのスキーマで提示されている場合にのみ使用してください。

MCP ツールの呼び出し

• ホストが graph_context を提示している場合は、自由形式の質問への使用を検討し、提示されたスキーマと応答形式のみを使用してください。それ以外の場合は、ホストが実際に公開しているツールから選択してください。
• MCP の出力オプションと応答メタデータは、ツール／スキーマによって異なります。現在のホストスキーマまたは応答で確認できない限り、response_format やメタデータフィールドがあると決めつけないでください。

MCP クライアントの設定

VS Code / Cursor（.vscode/mcp.json または .cursor/mcp.json）：

{
  "servers": {
    "graph-it-live": {
      "type": "stdio",
      "command": "graph-it",
      "args": ["serve"],
      "env": { "WORKSPACE_ROOT": "${workspaceFolder}" }
    }
  }
}

Claude Desktop（~/.config/claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "graph-it-live": {
      "command": "graph-it",
      "args": ["serve"],
      "env": { "WORKSPACE_ROOT": "/path/to/project" }
    }
  }
}

Claude Code CLI：

claude mcp add graph-it -- graph-it serve

Windsurf（~/.codeium/windsurf/mcp_config.json）：

{
  "mcpServers": {
    "graph-it-live": {
      "command": "graph-it",
      "args": ["serve"],
      "env": { "WORKSPACE_ROOT": "${workspaceFolder}" }
    }
  }
}

VS Code 拡張機能（代替）

Graph-It-Live は、Copilot Agent モード向けのネイティブ LM Tools を備えた VS Code 拡張機能でもあります（MCP の設定は不要です）。

マーケットプレイスからインストールするには、拡張機能（Ctrl+Shift+X）で「Graph-It-Live」を検索します。

拡張機能で MCP サーバーを有効にするには、VS Code の設定で graph-it-live.enableMcpServer を true に設定します。

よくあるワークフロー

「この関数を変更すると、何が壊れますか？」

graph-it scan
graph-it tool get_impact_analysis --filePath=/abs/path/src/auth/index.ts --symbolName=myFunction

「このモジュールの概要を教えてください」

# Outgoing: what this file imports and calls
graph-it summary src/auth/index.ts --format toon

# Incoming: who depends on this file
graph-it tool find_referencing_files --targetPath=/abs/path/src/auth/index.ts

モジュールが何を呼び出すか（呼び出し先）と、何から呼び出されるか（呼び出し元）の両方を常に確認してください。そうすることで、その役割と影響範囲の全体像を把握できます。

「プロジェクト内のデッドコードを見つけてください」

# Outgoing: symbols this file exports that nobody imports
graph-it check src/utils.ts
graph-it tool find_unused_symbols --filePath=/abs/path/src/utils.ts

# Incoming: confirm the file itself is not orphaned (nothing imports it)
graph-it tool find_referencing_files --targetPath=/abs/path/src/utils.ts

どちらの方向も確認する必要があります。ファイルが内部では使用されているように見えるシンボルをエクスポートしていても、プロジェクトの残りの部分からはまったく到達できない場合があります。

「main() からの実行を追跡してください」

graph-it trace src/index.ts#main --format mermaid

「循環依存はありますか？」

graph-it path src/index.ts

循環依存は自動で検出され、報告されます。

「プロジェクト全体で、この関数を呼び出しているのは誰ですか？」

# If advertised by the installed CLI, query_call_graph can report call sites
graph-it tool query_call_graph --filePath=/abs/path/src/utils/formatDate.ts --symbolName=formatDate --direction=callers --depth=1

MCP の場合は、まずホストが同等の呼び出しグラフツールを公開しているか確認し、その正確なスキーマを使用してください。呼び出し箇所だけでは、すべてのシンボル参照を確認したことにはなりません。

「アーキテクチャに関する質問に自然言語で回答してください」

graph-it query "how does the dependency index get rebuilt"

「オンボーディング用のウィキを生成してください」

graph-it wiki --output wiki

「マージ前にプルリクエストをレビューしてください」

graph-it review-pr --base origin/main --format markdown

影響分析機能が公開されている場合は、影響度が高または重大なすべてのシンボルについて、追加の確認を行ってください。報告された制限事項は、手動レビューの対象として扱います。

更新

graph-it update は、上記の確認ポリシーに従う場合にのみ実行してください。成功したら、バージョンとインベントリを更新し、MCP サーバーの再起動についてホストと調整してください。

関連スキル

• dead-code-hunter — 内部で Graph-It-Live を使用し、安全性のランク付け付きで、プロジェクト全体のデッドコード削除計画を作成します。確認するだけでなく、削除したい場合に使用してください。
• onboarding-express — 新しい開発者向けに、あらゆるコードベースを Graph-It-Live で体系的に案内します。エントリーポイント、ビジネスロジック、最も複雑なモジュール、クリティカルパスの図を確認できます。
• pr-review — Git diff をローカルまたは GitHub Actions でレビューし、Graph-It-Live の根拠をマージ可能な指摘にまとめます。
• skill-manager — インストール済みのスキルを対話形式で管理（一覧表示／アンインストール）します。ローカルのスキル構成を整理する際に便利です。