graphify使い方ガイド｜コードとPDFを知識グラフ化しgrepの代わりに辿るClaude Codeスキル

Claude Codeでコードベースに質問するたびにGlob・Grep・Readが連鎖して、1回の質問で数十万トークンを消費した経験は多くの開発者にあるはずだ。graphify（Graphify-Labs/graphify） は、コードベースを事前に知識グラフへ圧縮し、AIアシスタントにgrepの代わりにグラフを辿らせるOSSスキルだ。PyPI graphifyy で配布されている。

Claude Code全体の使い方はClaude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引きを参照してほしい。

graphifyとは：grepの代わりにグラフを辿らせるClaude Codeスキル

Claude Codeなら/graphifyで起動し、対象ディレクトリのコード・SQLスキーマ・ドキュメント・論文・画像・動画から概念とリレーションを抽出する。出力は対話型HTML・JSON・GRAPH_REPORT.mdの3点で、後段のClaude/Codexはこのレポートを起点にナビゲーションする。

削減倍率は公式の看板から外れた。「Karpathy repos + 5 papers + 4 images（52ファイル）」の71.5倍、「graphifyソース + Transformer論文（4ファイル）」の5.4倍は古い main ブランチのREADMEに残っているが、2026年8月31日に確認した既定ブランチ v8 のREADMEには無い（撤回の告知は出ていない）。現在の公式ポジショニングは「grepの代わりにグラフを辿る」ことそのものだ。

検証環境: macOS 14.5 / Python 3.12 / Claude Code v2.x / 確認日 2026-05-02。pip install graphifyyによるインストール可否、graphify claude installが~/.claude/CLAUDE.mdとsettings.jsonに書き込む内容まで確認。トークン削減の倍率はREADME掲載値で、手元では測っていない。

graphifyの仕組み：3パスのパイプラインと出力

Pass 1 は .py .ts .js .go .rs .java .c .cpp .rb .cs .kt .scala .php .swift .lua .zig .ps1 .ex .m .jl .vue .svelte .sql など25言語から、クラス・関数・import・呼び出し関係・docstring・設計コメント（# NOTE: # WHY: # HACK:）を抜く。SQLは graphifyy[sql] で有効になり、テーブル・ビュー・外部キーがノードになる。Pass 2 は動画・音声（YouTube等のURLはyt-dlpで音声だけ取得）をfaster-whisperでローカル転写し、graphify-out/transcripts/にキャッシュする。Pass 3 はClaudeサブエージェントが並列で概念を抜き、各エッジに EXTRACTED（confidence 1.0）・INFERRED（0.0–1.0付き）・AMBIGUOUS（要レビュー）を付ける。

統合後はLeidenでコミュニティに分ける。READMEは「Clustering is graph-topology-based — no embeddings」と明記しており、Vector DBも埋め込みパイプラインも要らない。コードだけ更新したときはASTだけで再ビルドでき、LLMコールはゼロだ。

レポートには最大次数の god ノード、コード–論文エッジが上位に来る surprising connections、そのグラフが答えやすい4–5の suggested questions、設計理由を集めた rationale_for ノード、3つ以上のノードの集団関係を表す hyperedges が並ぶ。

graphifyのインストールとClaude Code常時ON連携

PyPIの正式パッケージ名は graphifyy（yが2つ） で、pip install graphifyは別物だ。オプションはextrasで切り替える。

pip install graphifyy
pip install 'graphifyy[mcp]'      # MCPサーバ機能
pip install 'graphifyy[video]'    # 動画/音声 (faster-whisper + yt-dlp)
pip install 'graphifyy[sql]'      # SQL DDLパース
pip install 'graphifyy[office]'   # docx/xlsx

graphify claude install

これでプロジェクトのCLAUDE.mdに「グラフがあればgraphify-out/GRAPH_REPORT.mdを先に読む」節が足され、.claude/settings.jsonにPreToolUseフックが登録される。フックはGlob/Grep直前に「graphify: Knowledge graph exists. Read GRAPH_REPORT.md for god nodes and community structure before searching raw files.」と差し込む。あとは/graphify .でgraphify-out/を作るだけで、アンインストールはgraphify claude uninstall。

CLAUDE.mdに書いただけでは指示が無視されることもあるが、フックはツール呼び出しの直前に割り込むのでガードとして効く。公式READMEは14ツールへのインストールを1コマンドで用意している。

フック対応のClaude Code・Codex・Gemini CLI・OpenCodeはグラフ参照を強制でき、Cursor・Kiro・AntigravityはruleのalwaysApply / inclusion: alwaysで近い動きをするが、強制力はフック版より弱い。

graphifyの基本コマンドとMCP連携

/graphify .                        # カレントディレクトリでグラフ構築
/graphify ./raw --update           # 変更ファイルのみ再抽出して既存グラフへマージ
/graphify ./raw --mode deep        # INFERREDエッジを攻めに抽出
/graphify ./raw --wiki             # コミュニティ単位でWikipedia風MDを生成
/graphify ./raw --graphml          # graph.graphml (Gephi/yEd向け)
/graphify ./raw --neo4j-push bolt://localhost:7687

/graphify add https://arxiv.org/abs/1706.03762        # 論文を取得し、グラフ更新
/graphify add <video-url> --whisper-model medium      # 動画→音声→転写→抽出

/graphify query "show the auth flow" --dfs            # 特定パスをDFSで追跡
/graphify query "..." --budget 1500                   # トークン上限を指定
/graphify path "DigestAuth" "Response"                # 最短パス
/graphify explain "SwinTransformer"                   # ノードの平易な説明

graphify hook install              # post-commit + post-checkoutでグラフ自動再ビルド
graphify update ./src              # コードのみ再抽出（LLMコール無し）
graphify merge-graphs repo1/graphify-out/graph.json repo2/graphify-out/graph.json --out cross-repo.json

--budgetで「この質問は1500トークン以内」という制約をグラフ側で強制でき、merge-graphsでマイクロサービス全体を1つのグラフで横断できる。公式READMEは「graph.jsonをプロンプトに丸ごと貼ってはいけない」と明記しており、graphify queryで必要なサブグラフだけを切り出すか、MCPサーバ経由でツールとして呼ばせる。MCPならquery_graph / get_node / get_neighbors / shortest_path が使える。

{
  "mcpServers": {
    "graphify": {
      "type": "stdio",
      "command": ".venv/bin/python3",
      "args": ["-m", "graphify.serve", "graphify-out/graph.json"]
    }
  }
}

WSL/Linuxでは、PEP 668対策で必ずvenvに入れる（公式READMEの注意書き）。抽出から外すパスは .gitignore と同じ構文の .graphifyignore に書け（vendor/・node_modules/・AGENTS.md など）、!による再包含も使える。

効く場面・効かない場面と、他のトークン削減手法との比較

プロンプト圧縮系は質問のたびにコストを払うが、graphifyは一度作ったグラフをすべての質問で使い回す。一般的なRAGが埋め込みの類似度で探すのに対し、graphifyは明示的なエッジを辿るので、リファクタリング・設計理解・影響範囲調査に向く。

チームでは公式READMEの推奨どおり graphify-out/ をコミットして共有し、manifest.json（mtimeベースでclone後に無効）と cost.json（個人のトークン記録）だけ .gitignore に入れる。

リポジトリ移管とプロジェクトの現在地

・https://github.com/safishamsi/graphify は https://github.com/Graphify-Labs/graphify へリダイレクトされる（curl -sIL で確認）。旧URLのリンクとcloneは引き続き動く
・既定ブランチが v6 から v8 に変わった。/blob/v6/... は残っているが最新版を指さない
・GitHub API実測で★112,633（2026-08-31時点）・fork 9,661・open issue 732。作成は2026年4月3日
・PyPIの graphifyy は 0.9.31（2026-07-30公開）で、公開済みリリースは通算199本
・READMEにはY Combinator S26のバッジと公式サイトが並び、「Graphify Labs」という会社のプロダクトになっている

ライセンスは Apache License 2.0（2026-08-01、GitHubのライセンスAPIと LICENSE 本文で確認）。商用利用もできるが、MITと違って特許グラントの明示と、配布時のNOTICE／変更点の告知という条件が付く。リリース頻度がきわめて高く、YC企業のプロダクトになった以上ライセンスや課金方針の変更も起こりうるので、CIやチームの環境ではバージョンを固定しておきたい。

# 現在のリモートURLを確認する
git remote -v

# 新しい組織アカウントのURLへ更新する
git remote set-url origin https://github.com/Graphify-Labs/graphify.git

# インストール済み graphifyy のバージョンを固定する
pip install "graphifyy==0.9.31"

graphifyはトークン削減ツールである以上に、コードベースを事前に理解可能な構造へ整形しておく作業を、AIアシスタントが扱える形に固めたスキルだ。READMEはAndrej Karpathyが/rawフォルダに論文・X投稿・スクリーンショットをまとめている話を引き、「graphifyはあの問題への答え」と位置付けている。

参照ソース

• Graphify-Labs/graphify（公式リポジトリ・旧 safishamsi/graphify）
• Graphify-Labs/graphify README（既定ブランチ v8）
• graphifyy — PyPI
• Graphify Labs（公式サイト）
• Leiden Algorithm論文（Traag, Waltman, van Eck 2019）
• tree-sitter 公式
• faster-whisper（公式リポジトリ）
• Claude Code Hooks 公式ドキュメント