graphkeeper

npx graphkeeper-cli build
npx graphkeeper-cli query co-change src/git.ts

Files that historically change alongside "src/git.ts":

     1  src/store.ts
     1  src/types.ts
     1  test/git.test.ts
     1  test/store.test.ts
     1  test/test-helpers.ts

（GraphKeeper の自身のリポジトリに対して、履歴のごく初期に実行した際の実際の出力です。コードベースにコミットが蓄積されるにつれて、同時変更の件数も増えていきます。）

サーバーもアカウントも埋め込み API も不要です。出力のすべては、すでにチェックアウト済みのリポジトリで git log から取得されます。

インストール

GraphKeeper は、独立しており、どちらも同等に正式なパッケージとして提供されています。ツールチェーンに合う方を選ぶか、両方をインストールしてください。どちらも同じ git log の同時変更シグナルを調べ、ディスク上の .graphkeeper/graph.json スキーマを共有するため、どちらで作成したストアも、もう一方で読み込めます。

# npm -- JavaScript/TypeScript CLI + library
npm install -g graphkeeper-cli
# or run it once with no install
npx graphkeeper-cli build

# PyPI -- Python CLI + library (genuine port, not a wrapper around the Node binary)
pip install graphkeeper-cli

npm パッケージには Node.js 18 以降が必要です。Python パッケージには Python 3.9 以降が必要です。どちらも PATH 上に git が必要です。Python パッケージの CLI エントリーポイントも graphkeeper です（例：graphkeeper build）。Python 固有の手順については python/README.md、各配布版のバージョン履歴については CHANGELOG.md をご覧ください。

クイックスタート

このリポジトリを含め、任意の git リポジトリに対して実行できます。

git clone https://github.com/RudrenduPaul/GraphKeeper.git
cd GraphKeeper
graphkeeper build

GraphKeeper build complete: /path/to/GraphKeeper

Co-change graph: 4 commit(s) analyzed, 80 file pair(s) found
graphify enrichment: skipped -- graphify was not found on PATH. Install it with
`uv tool install graphifyy` (or `pipx install graphifyy`) for symbol/call-graph
enrichment; GraphKeeper works fine without it, in co-change-only mode.

Wrote /path/to/GraphKeeper/.graphkeeper/graph.json

次に、照会してみましょう。

graphkeeper query co-change src/git.ts

Files that historically change alongside "src/git.ts":

     1  src/store.ts
     1  src/types.ts
     1  test/git.test.ts
     1  test/store.test.ts
     1  test/test-helpers.ts

graphify がインストールされている場合（uv tool install graphifyy）、graphkeeper build は自動的に、API キー不要でローカルに動作する graphify extract --code-only を呼び出し、そのシンボル／呼び出しグラフを同じストアにマージします。これにより、呼び出しグラフの照会が可能になります。

graphkeeper query calls mineCoChange

mineCoChange() (src/git.ts)

Calls (2):
  --> assertIsGitRepo()
  --> runGit()

Called by (1):
  <-- build()

（こちらも実際の出力です。graphify をインストールした状態で、このリポジトリに対して graphkeeper build を実行しました。）

graphify がインストールされていない場合、同じコマンドはクラッシュしたり空の結果を返したりせず、回答を得られない理由を正確に説明します。

Call-graph query for "mineCoChange" is not available.

graphify was not found on PATH. Install it with `uv tool install graphifyy`
(or `pipx install graphifyy`) for symbol/call-graph enrichment; GraphKeeper
works fine without it, in co-change-only mode.

すべてのコマンドで、スクリプトやエージェント向けの --json も利用できます。

graphkeeper query co-change src/git.ts --json

{
  "file": "src/git.ts",
  "results": [
    { "file": "src/store.ts", "count": 1 },
    { "file": "src/types.ts", "count": 1 },
    { "file": "test/git.test.ts", "count": 1 },
    { "file": "test/store.test.ts", "count": 1 },
    { "file": "test/test-helpers.ts", "count": 1 }
  ]
}

機能

• 静的なスナップショットではなく、実際のコミット履歴を分析します。 graphkeeper build はリポジトリの全履歴に対して git log --no-merges --name-only を実行し、同じコミット内で一緒に変更されたすべてのファイルの組み合わせを数えます。フォルダー構成やインポート文だけから関連性を推測するのではなく、時間の経過とともにコードベースが実際にどのように編集されてきたかをもとに答えを導きます。
• --max-files-per-commit で有用なシグナルを保護します。 ベンダーコードの取り込みや一括フォーマット変更で 400 個のファイルが変更された場合、そのコミット内のすべての組み合わせがノイズになってしまいます。既定の上限（100 ファイル）を超えるコミットはスキップするため、実際の関連性がノイズに埋もれるのを防ぎます。
• 呼び出しグラフによる拡充は任意で、必須ではありません。 graphify が PATH にある場合、graphkeeper build はローカルで graphify extract --code-only --no-cluster を実行し、生成されたシンボル／呼び出しエッジを同じストアにマージすることで、graphkeeper query calls を利用できるようにします。graphify がなくても、GraphKeeper は共変更のみのモードで引き続き動作し、その旨を明確に示します。失敗することはありません。
• すべてのコマンドに --json モードがあります。 graphkeeper query co-change <file> --json などのコマンドは機械可読な出力を返すため、エージェントの呼び出しコードはテキストを解析するのではなく、実際のデータ構造を処理できます。
• ゼロから実装した 2 つの実装が、同じスキーマを使用します。 npm パッケージ（src/、TypeScript）と PyPI パッケージ（python/src/graphkeeper/、Python）は、一方を他方でラップしたものではなく、独立した移植版です。どちらも同じ .graphkeeper/graph.json を読み書きするため、一方の CLI で構築したストアをもう一方からクエリできます。
• すべてのサブプロセス呼び出しで argv 配列を使用し、シェル文字列は使いません。 Git と graphify はどちらも引数のリストを使って spawnSync／subprocess.run 経由で呼び出されるため、分析対象リポジトリ内の細工されたコミットメッセージやファイル名がシェル構文として解釈されることはありません。

CLI リファレンス

Usage: graphkeeper [options] [command]

Options:
  -V, --version           output the version number
  -h, --help              display help for command

Commands:
  build [options] [path]  Mine git history for co-change and (if available)
                          merge in graphify's symbol/call graph
  query                   Query the GraphKeeper store built by
                          `graphkeeper build`
  help [command]          display help for command

graphkeeper build [path]

path（既定値：現在のディレクトリ）を走査し、全履歴に対して git log --no-merges --name-only を実行して、同じコミットで一緒に変更されたファイルの各組み合わせの回数を数えます。結果は .graphkeeper/graph.json に書き込みます。

オプション	説明
--json	人が読めるテキストではなく、機械可読な JSON を出力します
--max-files-per-commit <n>	指定した数より多くのファイルが変更されたコミットをスキップします（既定値：100）。一括フォーマット変更やベンダーコード取り込みのコミットによって、実際の共変更シグナルが埋もれるのを防ぎます
--no-graphify	graphify がインストールされていても、graphify による拡充をスキップします

graphify が PATH で検出される場合、build は .graphkeeper/ 内のディレクトリで graphify extract <path> --code-only --no-cluster（graphify 独自のヘッドレス、ローカル、API キー不要の AST 抽出経路）も実行し、そのノード／エッジを同じストアにマージします。ビルド出力には、拡充が含まれたかどうかが常に明確に示され、含まれなかった場合はスキップされた理由も示されます。

graphkeeper query co-change <file>

<file> と過去に一緒に変更されたファイルを、一緒に変更されたコミット数の多い順に一覧表示します。

オプション	説明
--json	人が読めるテキストではなく、機械可読な JSON を出力します
--limit <n>	結果数を制限します
--graph <path>	特定の graph.json へのパス（既定値：<cwd>/.graphkeeper/graph.json）

結果が見つかった場合の終了コードは 0、そのファイルに共変更データがまだない場合は 1、使い方またはファイルシステムのエラーが発生した場合は 2 です。

graphkeeper query calls <symbol>

最新の build で生成された graphify の calls エッジを使って、<symbol> の呼び出し元と呼び出し先を表示します。graphify による拡張を含むビルドの場合にのみ意味があります。含まれていない場合は、クラッシュしたり結果が何も表示されなかったりする代わりに、その理由を明確に説明します。

オプション	説明
--json	人が読めるテキストの代わりに、機械可読な JSON を出力します
--graph <path>	特定の graph.json へのパス（デフォルト：<cwd>/.graphkeeper/graph.json）

シンボルが見つかった場合は終了コード 0、見つからない場合（または拡張を利用できない場合）は 1、使用方法またはファイルシステムのエラーの場合は 2 です。

MCP サーバー

GraphKeeper にはModel Context Protocol サーバーが付属しています。これにより、AI コーディングエージェント（Claude、Cursor、または MCP 対応クライアント）は、人が CLI を手動で実行しなくても、変更履歴を調査し、グラフに直接問い合わせることができます。

追加パッケージをインストールします。

pip install "graphkeeper-cli[mcp]"

MCP クライアントの設定に追加します（Claude Desktop の場合は claude_desktop_config.json）。

{
  "mcpServers": {
    "graphkeeper": {
      "command": "uvx",
      "args": ["--from", "graphkeeper-cli", "graphkeeper-mcp"]
    }
  }
}

このサーバーは、指定されたサブコマンドと引数に --json を付けて、公開されている graphkeeper-cli npm パッケージ（npx graphkeeper-cli 経由）をシェルで実行し、解析済みの JSON 結果を返す、run というツールを 1 つ公開します。

run(["build", "."])
run(["query", "co-change", "src/git.ts"])

トランスポートは stdio のため、ホストするものはありません。MCP クライアントがサーバーをローカルのサブプロセスとして起動します。ソース：python/src/graphkeeper/mcp_server.py。

ライブラリ API リファレンス

両方のパッケージは、以下に示す実際にインポート可能な API を公開しています。コマンドラインは、同じ関数を呼び出す薄いラッパーです。

TypeScript / JavaScript（npm の graphkeeper-cli）

import { build, queryCoChange } from "graphkeeper-cli";

const result = build(".");
console.log(`${result.store.commitsAnalyzed} commit(s) analyzed`);

const coChange = queryCoChange(result.store, "src/git.ts");
for (const row of coChange.results) {
  console.log(row.count, row.file);
}

エクスポート	シグネチャ
build	build(targetPath: string, options?: BuildOptions): BuildResult
queryCoChange	queryCoChange(store: GraphKeeperStore, file: string, options?: { limit?: number }): CoChangeQueryResult
queryCalls	queryCalls(store: GraphKeeperStore, symbol: string): CallsQueryResult
findGraphifyNode	findGraphifyNode(nodes: GraphifyNode[], symbol: string): GraphifyNode | null
normalizeFileArg	normalizeFileArg(store: GraphKeeperStore, file: string): string
detectGraphify	detectGraphify(): { installed: boolean; version: string | null }
runGraphifyEnrichment	runGraphifyEnrichment(repoRoot: string): GraphifyEnrichment
mineCoChange	mineCoChange(repoPath: string, options?: { maxFilesPerCommit?: number }): CoChangeMiningResult
GitError	git 関連のエラーが発生した場合にスローされるエラーサブクラス
resolveRepoRoot	resolveRepoRoot(targetPath: string): string
readStore	readStore(repoRoot: string, overridePath?: string): GraphKeeperStore
writeStore	writeStore(repoRoot: string, store: GraphKeeperStore): string
PathSafetyError	解決されたパスがリポジトリルートの外に出る場合にスローされるエラーサブクラス
graphFilePath	graphFilePath(repoRoot: string): string

型（GraphKeeperStore、CoChangeEdge、GraphifyNode、GraphifyEdge、 GraphifyRawGraph、GraphifyEnrichment、BuildOptions、BuildResult、 CoChangeQueryResult、CallsQueryResult）は、コンパイル済み出力とともに .d.ts 宣言として提供されます。個別に生成されたドキュメントサイトはまだありません。

Python（PyPI の graphkeeper-cli）

from graphkeeper import build, query_co_change

result = build(".")
print(f"{result.store.commits_analyzed} commit(s) analyzed")

co_change = query_co_change(result.store, "src/git.py")
for row in co_change.results:
    print(row.count, row.file)

graphkeeper.__all__ がエクスポートするもの：build、query_co_change、query_calls、 find_graphify_node、normalize_file_arg、detect_graphify、 run_graphify_enrichment、mine_co_change、unquote_git_path、GitError、 resolve_repo_root、read_store、write_store、graph_file_path、 PathSafetyError に加え、GraphKeeperStore、CoChangeEdge、 GraphifyNode、GraphifyEdge、GraphifyEnrichment、BuildOptions、 BuildResult、CoChangeQueryResult、CoChangeResultRow、および CallsQueryResult の各データクラスです。上記の TypeScript エクスポート表と同じ名前を snake_case で表記しています。現時点では、別途生成されたドキュメントサイトはありません。 python/src/graphkeeper/__init__.py 冒頭の docstring で、このセクションと同じ内容を説明しています。

比較

	GraphKeeper	graphify	GitNexus	Greptile	Augment Code
機能	git log からファイル単位の同時変更を抽出	tree-sitter によるシンボル／インポート／呼び出しグラフの抽出、AI アシスタント向けスキル	CLI と MCP ツール（ネイティブ、ローカル）に加え、インストール不要のブラウザー／WASM モードをオプションで提供。構造解析と呼び出しフロー分析	グラフでインデックス化されたコードベースを対象とする、ホスト型 AI コードレビュー	ライブのコード依存関係グラフ（Context Engine）を備えたホスト型 AI コーディングプラットフォーム。コミット履歴とドキュメントのインデックス化にも対応
ローカルのみ？	はい。常にローカルです	はい。コード解析はローカルで行います（設定されている場合、ドキュメント／メディアのインデックス化ではバックエンドを呼び出します）	CLI／MCP の経路はローカルで動作します。ブラウザーモードはクライアント側で動作しますが、ホスト型ウェブアプリが必要です	いいえ。デフォルトでは利用できません。セルフホスト／エアギャップ環境での利用は Enterprise プランのみ対応しています	いいえ。クラウドでホストされており、セルフホストの選択肢は公開情報に記載されていません
無料／オープンソース？	はい。Apache-2.0	はい。Apache-2.0	いいえ。PolyForm Noncommercial 1.0.0	無料の Starter プランあり（1 シート、月 50 クレジット）。オープンソースではありません	無料で利用できるかは公開情報に記載されていません。料金はエンタープライズ向けの個別見積もりです
同時変更の抽出？	はい。これがツールの全機能です	いいえ	いいえ	いいえ	いいえ
GraphKeeper との関係	--	graphify がインストールされている場合、GraphKeeper は graphify のローカルな extract 出力から独自のストアを拡張します。機能を再実装するものではありません	提供形態が異なります（CLI＋MCP＋オプションのブラウザーアプリと、このプロジェクトのシンプルな CLI）。同時変更の抽出機能はありません	チーム／PR レビュー向けのホスト型製品であり、ローカルで動作する単一エージェント向けツールではありません	エンタープライズ向けコーディングアシスタントプラットフォームであり、単体で動作するローカル CLI ではありません

（競合製品が数値を公開していない場合、推測はせず「公開情報に記載されていません」としています。2026 年 8 月時点で、各プロジェクトの README、料金ページ、または公開サイトに基づいて確認しています。）

GraphKeeper とは何か、なぜ存在するのか

GraphKeeper は、npm と PyPI の両方で graphkeeper-cli として公開されているローカル CLI およびライブラリで、git log を調べ、ファイル単位の共変更、つまり特定のファイルと同じコミットで過去に編集されたファイルを特定します。そのデータを単一の JSON ファイル .graphkeeper/graph.json に書き込み、ネットワーク呼び出しを一切行わずにクエリへ回答します。

GraphKeeper が存在するのは、コードベースに詳しくない AI コーディングエージェントが単独で作業する際、「このファイルを変更すると、ほかに何が一緒に変更されることが多いか」という問いに答えるための手早い方法がないからです。毎回 git log --name-only を実行して結果を手作業で集計する必要があります。GraphKeeper は、その答えを一度事前計算してクエリ可能にします。スクリプトやエージェントが直接解析できる --json 形式にも対応しています。

GraphKeeper はシンボルやコールグラフの抽出を再実装するものではありません。 graphify（GitHub スター数 10 万以上、Apache-2.0、pip install graphifyy）は、すでに 36 種類の tree-sitter 文法を対象にこの処理を行い、Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot、その他 15 以上のアシスタント向けのスラッシュコマンドスキルとして提供されています（合計 20 以上）。graphify が PATH 上にある場合、graphkeeper build はローカルの graphify extract --code-only --no-cluster を呼び出し、その結果を同じストアに統合するため、graphkeeper query calls が使えるようになります。graphify がなくても、GraphKeeper は共変更のみのモードで動作し、失敗するのではなく、そのことを明示します。

仕組み

1. graphkeeper build は、リポジトリ全体の履歴に対して git log --no-merges --name-only を実行します（安全な argv 配列によるサブプロセス呼び出しを使用し、シェル文字列は決して使いません）。
2. 各コミットについて、一緒に変更されたファイルのすべての組み合わせを数えます。--max-files-per-commit で指定したファイル数（デフォルトは 100）を超えるコミットはスキップされるため、ベンダーコードの一括取り込みや大規模な整形コミットによって、本当の傾向が埋もれることはありません。
3. graphify が PATH 上で検出された場合、GraphKeeper はさらに、graphify 独自のローカル抽出モード（LLM も API キーも不要）である graphify extract <path> --code-only --no-cluster を .graphkeeper/ 内のディレクトリに対して実行し、その nodes／edges を同じストアに統合します。
4. 統合された結果は、.graphkeeper/graph.json に一度だけアトミックに書き込まれます。
5. graphkeeper query はそのファイルを読み込み、共変更またはコールグラフに関する質問に回答します。ネットワーク呼び出しは一切ありません。

セキュリティ

• git と graphify の呼び出しにはすべて、OS に直接渡す argv 配列を使用します（TypeScript では spawnSync、Python ではリストを使った subprocess.run）。シェル文字列は使わないため、コミットメッセージ、ファイル名、リポジトリパスがシェル構文として解釈されることはありません。
• .graphkeeper/ の出力パスは書き込みの前に必ず、解決済みのリポジトリルートと照合して検証されます（fs.realpathSync を介し、シンボリックリンクも含めて検証します）。そのため、悪意を持って作られたリポジトリであっても、GraphKeeper の書き込み先を .graphkeeper/ の外部へ誘導することはできません。
• テレメトリーもネットワーク呼び出しもなく、シークレットも扱いません。GraphKeeper が読み込むのは git log の出力と、任意で graphify 独自の graph.json のみです。書き込むファイルも .graphkeeper/graph.json のみです。

脆弱性の報告手順については、SECURITY.md を参照してください。

FAQ

GraphKeeper は汎用的なコードベースのナレッジグラフインデクサーですか？

単体では違います。graphkeeper build は git log を調べてファイル単位の共変更を特定し、そのエッジを .graphkeeper/graph.json に書き込みます。このファイルがシンボル／コールグラフも保持するようになるのは、graphify がインストールされていて、同じビルド中に統合される場合のみです。graphify が PATH 上にない場合、ストアには共変更データのみが格納され、graphkeeper query calls は空の結果を返すのではなく、そのことを明示します。

grep や git log にはない、GraphKeeper がエージェントにもたらすものは何ですか？ 「ここでどのファイルが一緒に変更されるか」への、事前計算済みでクエリ可能な回答です。 エージェントが毎回、自分で git log --name-only を実行してスキャンし、 結果を手作業で集計する必要はありません。すべてのコマンドに --json を指定することで、 人が読んで再入力するのではなく、スクリプトで利用できる回答になります。

インストール方法を教えてください。また、Windows でも動作しますか？

npm install -g graphkeeper-cli（Node.js 18 以降）または pip install graphkeeper-cli（Python 3.9 以降）でインストールできます。どちらも PATH 上に git が必要です。 どちらのパッケージにも OS 固有の分岐やネイティブバインディングは含まれておらず、PyPI の 掲載情報では Operating System :: OS Independent に分類されています。そのため、git と サポート対象の Node または Python ランタイムを利用できる環境であれば、Windows、macOS、Linux の いずれでも同じように動作します。

エンリッチメントに使用するリンク先ツール、graphify とはどう違いますか？

両者は異なる問いに答えます。graphify は tree-sitter を使って、36 の言語のソースからシンボル、 インポート、呼び出しグラフを直接抽出します。GraphKeeper はコミット履歴を分析し、過去にどの ファイルが一緒に編集されたかを調べます。graphify が計算する必要のないシグナルです。GraphKeeper は、 graphify が利用可能な場合、自身のローカルな extract コマンドを呼び出して結果を統合します。 tree-sitter による解析を一から再実装するわけではありません。どちらかがもう一方を置き換えるものでは ありません。GitNexus、Greptile、Augment Code が両者とどう異なるかについては、上記の比較表を ご覧ください。

GraphKeeper が実際に動作しなくなったり、結果が空になったりするのはどんな場合ですか？

実際に起こりうるケースは 2 つあります。どちらもドキュメントに記載されており、クラッシュするわけでは ありません。浅い git クローン（GitHub Actions のデフォルトである fetch-depth: 1）には分析できる 履歴がないため、build は 0 commit(s) analyzed と報告し、空の co-change グラフを書き込みます。 全履歴（fetch-depth: 0）が必要です。もう一つは、直近の build で graphify が PATH 上にあった場合に 限り、query calls が結果を返すことです。そうでない場合は、シンボルが存在しないかのように装うのではなく、 コマンドがその旨を明確に説明します（graphify was not found on PATH...）。

完全には信頼できないリポジトリに対して実行しても安全ですか？

すべての git と graphify の呼び出しは、argv 配列を通じて OS に直接渡されます（spawnSync / Python の subprocess.run にリストを渡し、シェル文字列は使いません）。そのため、ファイル名や コミットメッセージがシェル構文として解釈されることはありません。.graphkeeper/ への書き込みはすべて、 実行前にシンボリックリンクも含めて解決済みのリポジトリルートとの照合を行います。このツールには ネットワーク呼び出しが一切ないため、対象に指定したリポジトリの情報がマシンの外に出ることはありません。

npm CLI は Python 版の単なるラッパーですか？ それともその逆ですか？

どちらでもありません。両者は一から独立して実装されています（TypeScript 版は src/、Python 版は python/src/graphkeeper/）。同じ .graphkeeper/graph.json スキーマ、サブコマンド、フラグ、終了コードに 対応しています。一方で構築したストアを、もう一方で読み込めます。Python 版の独自のテストスイートは TypeScript の vitest スイートから移植したもので、テスト数は 78 件です。他方の言語の出力をモックするのではなく、 実際のサブプロセス CLI 呼び出しに対して実行されます。執筆時点では、クリーンインストール環境で両方の テストスイートが合格しています。TypeScript 側は 78/78（npm test）、Python 側は 78/78 （pytest）です。

ライセンスは何ですか？ 商用利用できますか？

npm パッケージと PyPI パッケージの両方に Apache License 2.0 が適用されます。デュアルライセンスや 別途の商用プランはありません。商用利用、変更、再配布が許可されており、著作権表示と Apache の標準的な 特許許諾が必要です。全文は LICENSE をご覧ください。

貢献

Issue や PR を歓迎します。TypeScript パッケージをソースからビルドするには、次の手順を実行します。

git clone https://github.com/RudrenduPaul/GraphKeeper.git
cd GraphKeeper
npm install
npm run build
npm test
npm run lint
npm run typecheck

Python パッケージについては、python/README.md をご覧ください。両方のコードベースを 対象とした貢献ガイドラインの全文は、CONTRIBUTING.md にあります。

ライセンス

Apache License 2.0