Graphpilot

GraphPilot

コーディングエージェントのための構造的メモリ。
マシン上だけで動作する、リファクタリングに強く、ブランチを認識し、根拠に裏付けられたコードグラフです。

クイックスタート · ツール · 仕組み · エディターの設定 · 制限事項 · ベンチマーク

---

これは何か

GraphPilot はローカル CLI と MCP サーバーで、TypeScript／JavaScript リポジトリを構造グラフ（シンボル、呼び出し元、呼び出し先、影響範囲）にインデックス化し、Claude Code、Cursor、Cline、Windsurf、Continue などのコーディングエージェントに公開します。これにより、エージェントが会話のたびに同じファイルを再び grep する必要がなくなります。

解決するのは次の問題です。各セッションがゼロから始まるため、エージェントはトークンを浪費し、関数名を幻覚し、構造上の関係（「これは何から呼び出されているか？」「名前を変更すると何が壊れるか？」）を見落とします。その間を埋める永続的な構造的メモリが GraphPilot です。

トークンコストを削減。幻覚を削減。リファクタリングをより安全に。

実際のコーディングエージェント（claude-sonnet-4-5）に、約 300 ファイルの Node.js フレームワークである fastify についての構造に関する質問 40 件を与え、ファイルの読み取りだけを許可します。次に、GraphPilot の 4 つのツールを与えて、同じ 40 件の質問をします。GraphPilot を使うエージェントはトークンを 61 % 削減し、コストは $8.88 から $3.68 に低下し、1 セッションあたり $5.20 節約できます。さらに、正解数も減るどころか増えます（37 件対 33 件）。モデル、質問、リポジトリは同じで、違いは構造インデックスの有無だけです。再現方法 →

別の正確性ベンチマークでも、精度の高さによってこの削減効果が裏付けられています。標準化された構造クエリ 10 件で、GraphPilot のスコアは F1 0.89、grep は 0.42です。一方、読み取るバイト数は 99.9 % 少なく（721 B 対 528 KB）、バイトコストの優位性は大規模でも維持されます。microsoft/TypeScript（601 ファイル、1 万 7 千シンボル、10 秒で 7 万の呼び出しエッジ）をインデックス化すると、クエリは 1 ミリ秒未満で、読み取りバイト数を 99.99 % 削減できます。方法の詳細 →

1 つのバイナリで 2 つのモード

GraphPilot は、2 つの実行モードを備えた単一の npm パッケージ（@graphpilot-oss/graphpilot）として提供されます。ほとんどのユーザーは両方のモードを使います。

モード	コマンド	機能
CLI	graphpilot index <path>	リポジトリを走査し、構造グラフを構築して、~/.graphpilot/ に書き込みます
	graphpilot watch <path>	グラフを最新の状態に保ちます（ファイル保存あたり約 10 ms）
	graphpilot status <path>	ヘルスチェックです。グラフの最終更新時刻、ファイル／シンボル／エッジの件数を表示します
MCP サーバー	graphpilot mcp	stdio 経由で MCP を使用します。コーディングエージェントはこれを呼び出してグラフを照会します

処理の流れ： CLI がインデックスを一度構築し（watch が最新の状態を保ちます）、MCP サーバーをコーディングエージェントとの通信に使います。自分で MCP サーバーを起動する必要はありません。エージェントの MCP 設定で一度 graphpilot mcp を指定するだけで、エージェントがセッションごとに起動します。

コードグラフに CLI からアクセスするだけでよい場合（エージェントを使わない場合）は、graphpilot index を実行し、その後 graphpilot stats を実行するか、graph.json を直接確認してください。エージェントとの連携だけを使う場合も、graphpilot index を一度実行する必要があります。MCP サーバーはディスク上のグラフに対して読み取り専用です。

他との違い

他のコードグラフツールは、リポジトリを静的なデータの塊として扱います。インデックスを一度作成したら、ブランチの認識も、回答の出所を示す根拠もないまま、いつまでも照会し続けます。GraphPilot は、他のツールにはない次の 3 つの特性を中心に設計されています。

• 🔍 根拠アンカー。 すべてのツール応答で、各シンボルと呼び出し箇所に file:line @ sha が付与されます。エージェントはアンカーをそのまま引用でき、すぐに確認できます。該当行に移動するだけで、幻覚を見抜けます。
• 🌿 差分に基づく影響分析。 gp_impact に since: <commit|branch> を渡すと、結果が実際にブランチで変更されたファイルに絞り込まれます。git diff | xargs grep の代わりに、PR の範囲に限定したリファクタリング分析を 1 回の呼び出しで行えます。
• 🪵 デフォルトでワークツリーを認識。 git worktree add で作成した 2 つのブランチは、手動設定なしでそれぞれ別のインデックスになります。サブディレクトリから graphpilot index ./src/feature を実行しても、ワークツリーのルートに透過的に再設定されます。--no-worktree で無効にできます。

さらに、ローカルファースト（テレメトリーなし、リモート呼び出しなし。src/ 自体に対する ESLint ポリシーで強制）、決定論的（同じリポジトリからは同じグラフを生成）、watch モードによる 1 秒未満の差分更新を備えています。

クイックスタート

前提条件

• Node.js ≥ 20（確認するには node --version を実行）
• MCP 対応のコーディングエージェント（Claude Code、Cursor、Cline、Windsurf、または Continue）
• インデックスを作成する TypeScript または JavaScript のリポジトリ

最初から最後までの所要時間：約 3 分。

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

npm install -g @graphpilot-oss/graphpilot
# or: pnpm add -g @graphpilot-oss/graphpilot
# or one-shot, no install: npx @graphpilot-oss/graphpilot <command>

PATH に追加されたことを確認します。

graphpilot --version
# → 0.1.0

command not found: graphpilot と表示された場合、グローバル npm の bin ディレクトリが PATH に含まれていません。npm config get prefix を実行して <prefix>/bin をシェルの PATH に追加するか、上記の npx 形式を使用してください。

2. リポジトリの構造インデックスを作成する

プロジェクトごとに一度実行します。ソースツリーを走査し、tree-sitter で各 TS/JS ファイルを解析して、シンボルと呼び出しエッジを抽出し、グラフを ~/.graphpilot/<repo-id>/graph.json に書き込みます。

graphpilot index ~/code/my-app

indexed 412 files · 3,981 symbols · 7,204 edges · 1.8s のような 1 行の概要が表示されます。

3. コーディングエージェントに接続する

GraphPilot は stdio 経由で MCP を使用します。このサーバーエントリーをエージェントの MCP 設定に追加してください。サポートされているすべてのクライアントで、同じ 2 行形式を使用します。

{
  "mcpServers": {
    "graphpilot": {
      "command": "graphpilot",
      "args": ["mcp"]
    }
  }
}

このファイルの場所はクライアントによって異なります（~/.cursor/mcp.json、~/.claude.json、Cline の設定パネルなど）。各エージェントの正確なファイルパスを指定した設定例は examples/ にあります。お使いのクライアントに対応するものをコピーしてください。

エージェントを再起動します。これで、gp_recall、gp_callers、gp_impact、gp_index の 4 つのツールが利用できるようになります。それぞれの機能とエージェントが使用すべき場面については、以下の4 つのツールを参照してください。

4. 試してみる

エージェントに grep させる代わりに、構造に関する質問をしてみましょう。

「gp_impact を使って、parseToken の名前を変更した場合に壊れるものをすべて表示してください。」

クリックして直接移動できる file:line @ sha アンカー付きの応答が表示されるはずです。エージェントがツールを使わない場合は、「gp_ MCP ツールを使って」と明示的に指示してください。ツールがまったく表示されない場合は、MCP 設定が読み込まれていません。graphpilot doctor を実行して原因を特定するか（または docs/troubleshooting.md を参照してください）、その後エージェントを再起動してください。

5. 編集に合わせてインデックスを最新の状態に保つ（任意ですが推奨）

graphpilot watch ~/code/my-app

ファイルを保存するたびに、10 ms 未満で差分更新されます。ターミナルのタブで実行したままにしてください。

6. エディターごとのルーティングルールをリポジトリに追加する（任意）

graphpilot init

インストール済みのエディター（Cursor、Claude Code、Cline、Windsurf、Continue）を自動検出し、対応するルールファイル（.cursorrules、CLAUDE.md など）を現在のディレクトリに書き込みます。このルールにより、エージェントは grep より先に gp_* ツールを使用するようになります。

graphpilot init --all            # write rules for every supported editor
graphpilot init --client cursor  # one editor only
graphpilot init --dry-run        # preview without writing

スクリーンショット付きの 5 分間の詳しい手順については、docs/quickstart.md を参照してください。

4 つのツール

GraphPilot は 4 つの MCP ツールを提供します。それぞれ、エージェントが grep とファイルの読み込みで解決することになる、構造に関する質問に答えます。

gp_recall — 名前でシンボルを検索する

エージェントが「X はどこで定義されていますか？」と尋ねる場合や、シンボルについて推論する前に関数の場所を特定する必要がある場合に使用します。

• 入力： { query, limit?, substring?, path? }
• 戻り値： 名前に一致するシンボル（デフォルトでは大文字・小文字を区別しない完全一致。部分一致には substring: true を指定）。それぞれに file:line @ sha が付きます。
• 置き換える操作： grep -rn "function X" を実行し、各結果を読んで実際の定義を見つける操作です。

Agent: gp_recall({ query: "parseToken" })
→ parseToken (function) — src/auth.ts:42 @ a1b2c3d
  export function parseToken(raw: string): Token | null

gp_callers — 呼び出し元（または呼び出し先）を一覧表示する

エージェントが「X を呼び出しているのは誰ですか？」または「X は何を呼び出していますか？」を知る必要がある場合に使用します。これはリファクタリングにおける基本的な 2 つの質問です。

• 入力： { symbol, direction?: 'callers' | 'callees', limit?, includeUnresolved?, path? }
• 戻り値： シンボルが対象（呼び出し元）または呼び出し元（呼び出し先）であるすべての呼び出しエッジとアンカーです。
• 置き換える操作： grep -rn "X(" を実行した後、コメント、文字列、名前が変更されたシャドーを手作業で除外する操作です。

Agent: gp_callers({ symbol: "authenticate", direction: "callers" })
→ login → authenticate — src/routes/login.ts:18 @ a1b2c3d
→ refreshSession → authenticate — src/session.ts:64 @ a1b2c3d

gp_impact — 1 回の呼び出しで影響範囲を把握

エージェントが「X の名前を変更すると何が壊れますか？」や「これに依存しているものは何ですか？」と尋ねたときに使います。通常、エージェントが解決する質問の中で、最もコストのかかる質問です。

• 入力: { symbol, depth? (1–5, default 3), since?, path? }
• 戻り値: 直接の呼び出し元、BFS の深さごとにグループ化された推移的な呼び出し元、影響を受ける可能性が高いテスト、公開 API フラグ、概要統計。
• 主な特長: since: 'main' を渡すと、結果をブランチで実際に変更したファイルに限定できます。git diff を駆使せずに、PR に範囲を絞ったリファクタリングレビューができます。

Agent: gp_impact({ symbol: "extractSymbols", depth: 2, since: "main" })
→ Direct callers (2):    indexDirectory, applyUpdate
→ Depth-2 callers (1):   cmdIndex
→ Tests affected (3):    tests/indexer.test.ts, tests/symbols.test.ts, tests/cli.test.ts
→ Public API:            no

gp_index — エージェント内からインデックスを更新

エージェント（またはユーザー）が一連の構造的な編集を行い、シェルに切り替えずにグラフへ反映したいときに使います。

• 入力: { path? }
• 戻り値: リポジトリを再インデックスし、パスごとのクエリーキャッシュを無効化します。
• 連携先: graphpilot watch を使うと、明示的な再インデックスの間も 10 ミリ秒未満で増分更新できます。

仕組み

データフローは一方向です：ソース → ツリー → シンボル + エッジ → JSON → クエリー → エージェント。GraphPilot がコードを変更することはありません。

ファイル参照付きのパイプライン全体の説明は、docs/architecture.md をご覧ください。

ツールの使い分け

エージェントがこれから行おうとしていること	使うツール…	理由
関数名で grep する	gp_recall	1 回の呼び出しで済み、コメントや文字列による誤検出もありません
「X を呼び出すのは誰か」を探して 20 個のファイルを読む	gp_callers	事前計算済みの逆引きインデックスにより、1 ミリ秒未満で処理できます
名前変更やシグネチャ変更を計画する	gp_impact	直接・推移的な呼び出し元、テスト、公開 API を 1 回の呼び出しで確認できます
PR の構造的な影響範囲をレビューする	gp_impact({ since: 'main' })	差分を分析し、ブランチで影響を受ける呼び出し元だけに限定します
複数ファイルを編集した後、再度 grep する	gp_index	増分処理により、次の呼び出しで編集内容を参照できます

文字列リテラル、エラーメッセージ、設定値、または TS/JS 以外の言語に含まれるものには、引き続き grep を使ってください。 GraphPilot がインデックスするのはコード構造であり、テキストではありません。

エディターの設定

GraphPilot は stdio 経由で MCP を利用するため、MCP 対応クライアントであれば使用できます。すぐに貼り付けられる設定は examples/ にあります。

クライアント	フォルダー
Claude Code（Anthropic）	examples/claude-code/
Cursor	examples/cursor/
Cline（VS Code 拡張機能）	examples/cline/
Windsurf（Codeium）	examples/windsurf/
Continue.dev	examples/continue/
その他の MCP クライアント	docs/mcp-setup.md をご覧ください

各フォルダーには、手順を説明する README.md、貼り付ける正確な JSON を記載したサンプル設定ファイル、そして（クライアントが対応している場合）構造に関する質問でエージェントが自動的に GraphPilot を利用するためのルーティングテンプレートが含まれています。

プライバシーとセキュリティ

GraphPilot は、設計上もビルドゲート上も、ローカルファーストを約束します。

• テレメトリーなし、リモートへの呼び出しなし。例外はありません。 検証可能です。src/ には http、fetch、axios、分析関連のインポートが一切ありません。ESLint ルールと、そのルールが禁止対象のインポートごとに機能することを証明するメタテストによって強制されます。
• child_process、exec、spawn は使用しません。 Git の情報は、純粋な JavaScript ヘルパーを使って .git/ から直接読み取ります。
• ソースコードがマシンの外に出ることはありません。 ~/.graphpilot/ に保存されるのは、構造メタデータ（名前、場所、シグネチャ、呼び出し関係）のみです。
• シグネチャは、一般的なシークレットのパターン（OpenAI/Anthropic の sk-、GitHub の ghp_／ghs_、AWS の AKIA、JWT、PEM ヘッダー、Slack/Stripe のトークン）を対象に、ディスクへの書き込み前にマスキングされます。
• 厳格なファイル権限： ディレクトリは 0o700、ファイルは 0o600 です。
• 読み込み時にスキーマを検証します： 改ざんまたは破損した graph.json は、エージェントに悪影響を与える代わりに「インデックスなし」として扱われます。
• すべての MCP ツールに、独自実装の入力バリデーターを適用します。 未知のフィールドは拒否され、すべてのフィールドで型が検証され、数値は範囲が検証され、文字列には長さの上限が設定されます。

脅威モデルと防御ごとのテストに関する参照先は、docs/architecture.md にあります。セキュリティ上の問題は、SECURITY.md に従って報告してください。

制限事項

GraphPilot v0.1 では、小さく鋭い形でリリースするため、意図的にトレードオフを設けています。

• TS/JS のみです。 Python、Rust、Go、Java は v1 の対象外です。Python の追加は、需要に応じて v0.2／v0.3 で検討します。
• 名前ベースのリゾルバーです（インポートパスの追跡や、型ベースのメソッドディスパッチはありません）。解決率は、エッジの約 25～35％がリポジトリ内のシンボルに解決される見込みです。残りは標準ライブラリまたはサードパーティです。エージェントが実際に尋ねる質問（「このリポジトリで X を呼び出しているのは誰？」）に、この単純なリゾルバーが正しく答えられるため、これで十分です。
• セマンティック検索はありません。 gp_recall は名前のみを対象とします。「このスニペットに似たコードを探す」機能は、30 人以上のユーザーから要望があるまで保留します。
• .graphpilotignore はまだありません（デフォルトでは node_modules、dist、build、.git、coverage、.next、.nuxt、.cache、out、*.d.ts をスキップします）。
• クエリごとに単一のリポジトリが対象です。 ワークスペースの抽象化は v1.x のロードマップに含まれています。

緩和策を含む全リストは、docs/limitations.md をご覧ください。

FAQ

コードがどこかに送信されますか？ いいえ。src/ にネットワーク通信のコードはなく、テレメトリーも更新チェックもありません。ESLint ルールによって、ビルドゲートでこれらを追加できないようにしています。

エディターの動作が遅くなりますか？ MCP サーバーは、エージェントがツールを呼び出すまでアイドル状態です。初回の遅延読み込み後、ツールの呼び出しは 1 ミリ秒未満です。ウォッチモードでは、ファイル保存ごとに約 3～10 ミリ秒が追加されます。

ブランチを切り替えると、グラフはどうなりますか？ git worktree を使用している場合、worktree ごとに別のグラフが自動的に作成されます。git checkout で切り替える単一の作業コピーでは、グラフは最後の gp_index（またはウォッチモードによる更新）の状態を反映します。ブランチを切り替えた後に gp_index を実行して更新してください。

セッションのたびに再インデックスする必要がありますか？ いいえ。グラフは ~/.graphpilot/<repo-id>/graph.json に保存されます。大規模な変更の後に再インデックスしてください。それ以外の場合は、ウォッチモードがグラフを増分更新して最新の状態に保ちます。

なぜ最初に TypeScript／JavaScript に対応したのですか？ メンテナーが課題を感じていた分野であり、tree-sitter-typescript は 1 つの文法で TS、TSX、JSX、JS をカバーできるためです。次に追加される可能性が高いのは Python です。GitHub Discussion で投票してください。

LSP と比べてどう違いますか？ LSP は 1 つのエディターと 1 つのバッファーを対象とし、クエリのたびに再計算します。GraphPilot はエディターに依存せず、セッションをまたいで状態を保持し、LSP では一貫して提供されない構造的な質問（呼び出し元、影響範囲）に答えます。

エージェントからツールが見えない、または何かが動作しません。 graphpilot doctor を実行してください。Node、PATH、インデックス、MCP ハンドシェイク、クライアントごとの設定をまとめて確認します。症状ごとの解決方法は、docs/troubleshooting.md にあります。

ドキュメント

• docs/quickstart.md — 5 分でわかる使い方
• docs/mcp-setup.md — クライアントごとの設定リファレンス
• docs/troubleshooting.md — 症状別の解決方法（まずは graphpilot doctor を実行してください）
• docs/architecture.md — ファイル参照付きのパイプライン解説
• docs/limitations.md — v1 の注意点（お読みください）
• bench/README.md — ベンチマークの方法と結果
• examples/ — 対応するすべてのクライアント向けの、そのまま貼り付けて使える設定

コントリビューション

GraphPilot は小規模で、明確な方針を持つプロジェクトです。コントリビューションを歓迎します。まずは CONTRIBUTING.md をご覧ください。特に、機能を提案する前に 「v1 で取り組まないこと」 のセクションをお読みください。

セキュリティ上の問題を見つけましたか？公開 issue を作成するのではなく、SECURITY.md に従ってください。

ライセンス

Apache-2.0。Copyright 2026 Akshay Sharma — [email protected]