cssgraph

---

cssgraph を使う理由

AI エージェントが CSS を理解しようとするとき、たとえば .btn-primary の定義場所、含まれるプロパティ、それにカスケードするセレクター、そのクラスを参照する JSX コンポーネントなどを調べるには、時間のかかる方法が必要でした。ファイルを一つずつ grep、glob、Read で検索し、手作業でカスケードを再構築します。

cssgraph は、エージェントが必要とする正確なスタイルコンテキストを 1 回の呼び出しで提供します。 スタイルシートに含まれるすべての className、CSS プロパティ、変数、アットルールを事前に構築したナレッジグラフです。ファイルを探し回る代わりに、エージェントは質問を 1 つするだけで、プロパティ、上書き、詳細度、参照元、ファイル単位の影響範囲をすべて取得できます。

---

インストール

人間向け

このプロンプトをコピーして、LLM エージェント（Claude Code、Cursor、Codex など）に貼り付けてください。

Install and configure cssgraph by following the instructions here:
https://raw.githubusercontent.com/mack-peng/cssgraph/main/docs/guide/installation.md

または、インストールガイドをご覧ください。とはいえ、エージェントに任せるのがおすすめです。人間は設定を打ち間違えがちです。

LLM エージェント向け

インストールガイドを取得して、その手順に従ってください。

curl -s https://raw.githubusercontent.com/mack-peng/cssgraph/main/docs/guide/installation.md

---

クイックスタート

1. 初期化

npm i -g cssgraph
cd your-project
cssgraph init --workers 8

すべてのスタイルファイル（CSS、SCSS、Less、Sass）、JSX/TSX の className 参照、 CSS-in-JS、CSS Modules、およびビューテンプレート（ERB/Haml/HTML）をインデックス化し、すべての MCP ツールを利用可能にします。

--workers <n> を渡すと、並列解析スレッド数を指定できます（デフォルトは CPU コア数 - 1）。

Node.js >= 22.5.0 が必要です（node:sqlite のため）。

2. エージェントを接続する

cssgraph mcp-install

opencode、Claude Code、Cursor、Codex CLI、Gemini CLI、 Hermes Agent、Antigravity IDE、Kiro を自動検出して設定します。MCP サーバーの設定、指示ブロック、 および エージェントスキル（SKILL.md と references/pitfalls.md）を書き込みます。これにより、 各 cssgraph ツール 13 個を使うタイミング、ツールをワークフローとして連携させる方法、 避けるべき落とし穴をエージェントに教えます。

または、任意の MCP エージェントに手動で追加できます。

{
  "mcpServers": {
    "cssgraph": {
      "type": "stdio",
      "command": "cssgraph",
      "args": ["serve", "--mcp"]
    }
  }
}

3. 同期はもう不要

自動同期はデフォルトで有効です。MCP サーバーがプロジェクトを監視し、ファイルが変更されるたびにグラフを更新します。エージェントによるコードの編集中も、CSS ファイルの追加、変更、削除時も同様です。インデックスが古くなることはありません。

---

仕組み

┌───────────────────────────────────────────────────────────┐
│                      AI Agent                              │
│                                                           │
│  "What code files use .btn-primary?"                      │
│      calls cssgraph_rule — one tool call                  │
│                             │                             │
└─────────────────────────────┬─────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────┐
│                  cssgraph MCP Server                       │
│                                                           │
│ rule · O(1) exact selector lookup · loose/strict impact   │
│ explore · properties + overrides + specificity + callers  │
│                             │                             │
│                             ▼                             │
│               SQLite knowledge graph                      │
│     classNames · properties · variables · at-rules        │
│            edges · FTS5 full-text search                  │
└───────────────────────────────────────────────────────────┘

1. 抽出 — PostCSS が CSS／SCSS／Less／Sass を AST に解析します。CSS-in-JS（styled.div）、JSX の className 参照、テンプレートの class 属性は、.jsx／.tsx／.erb／.haml ファイルから抽出されます。
2. 保存 — すべてのデータは、FTS5 全文検索を備えたローカルの SQLite データベース（.cssgraph/cssgraph.db）に保存されます。書き込み性能を高めるため、WAL モードとバッチコミットを使用します。高速化のため、一括読み込み中は FTS トリガーと一意インデックスの作成を延期します。
3. グラフ — 関連するノードをエッジで接続します。contains（セレクター→プロパティ）、nests（親→子セレクター）、overrides（詳細度の高いセレクターが低いセレクターを上書き）、imports（ファイル→インポートされたファイル）、references（JSX／ビューのファイル→className、プロパティ→CSS 変数）。
4. Git 優先のスキャン — git ls-files でファイルをすばやく検出します。Git 管理されていないプロジェクトでは、ファイルシステムの走査にフォールバックします。
5. 並列解析 — ファイルをバッチ単位で Promise.all を介してワーカースレッドに振り分けます。解析は並行して完了し、正確性を保つため、結果はファイル順に書き出されます。
6. 自動同期 — OS のネイティブなファイルイベントを監視し、デバウンス処理を行って差分を同期します。

---

CLI リファレンス

cssgraph init [path] [-w, --workers <n>]  # Initialize + build graph
cssgraph index [path] [-w, --workers <n>]  # Rebuild from scratch
cssgraph query <className>                 # Search for className selectors
cssgraph explore <query...>                # Full style context for a className
cssgraph details <selector>                # O(1) exact selector → file:line lookup
cssgraph rule <selector> [--strict]        # Selector impact: exact + loose/strict files
cssgraph impact-selector <selector>       # Code files affected by a selector
cssgraph impact <className>                # Blast radius of changing a className
cssgraph unused                            # Find unreferenced class selectors
cssgraph cascade <className>               # Visualize cascade path
cssgraph diagnose <className> [chain...]   # Static anchor diagnosis (height/scroll)
cssgraph property <query...>               # Search by CSS property value
cssgraph files [path]                      # Project style file tree
cssgraph status [path]                     # Index statistics
cssgraph sync [path]                       # Incremental update
cssgraph serve --mcp                       # Start MCP server
cssgraph mcp-install                       # Auto-wire to your AI agent (alias: install)
cssgraph skill-install                     # Install/update SKILL.md only (no MCP config changes)
cssgraph skill-uninstall                   # Remove SKILL.md only (no MCP config changes)
cssgraph mcp-uninstall                     # Remove from your AI agent (alias: uninstall)
cssgraph version                           # Print installed version

JSX とビューファイルのスキャン（デフォルト）

cssgraph は常に次のファイルをスキャンします。

• JSX／TSX／JS／TS／ES6 — className 参照、CSS-in-JS、CSS Modules
• ビューテンプレート — .erb、.haml、.html ファイル内の class="..." 属性と、Haml の .classname 省略記法

これにより、cssgraph_impact、cssgraph_callers、cssgraph_rule は、各 className を参照するコンポーネントファイルとテンプレートファイルの両方を追跡できます。

プロジェクト	合計ファイル数	初回インデックス作成	ノード	エッジ
小規模	~50	~15s	~16K	~50K
本番用モノレポ	~11K	~3-5m	~780K	~22M

---

MCP ツール

ツール	目的
cssgraph_explore	主なツール：className のスタイルコンテキスト全体（プロパティ、上書き、詳細度、呼び出し元）を表示
cssgraph_search	名前で className セレクターを検索
cssgraph_callers	className を参照している JSX コンポーネントを検索
cssgraph_impact	className を変更した場合の影響範囲
cssgraph_rule	CSS セレクター全体の影響範囲（完全一致＋緩い／厳密なファイルへの影響）
cssgraph_impact_selector	CSS セレクターの影響を受けるコードファイル（JS／TS／JSX／TSX）を検索
cssgraph_details	セレクターの O(1) 完全一致検索（エッジなし、軽量）
cssgraph_unused	参照元のないクラスセレクターを検索
cssgraph_cascade	className のカスケード経路を可視化
cssgraph_diagnose	スクロール／高さの問題に対する静的なアンカー診断 — 祖先チェーンに沿って高さの宣言を DEFINITE／INDEFINITE／UNVERIFIABLE に分類
cssgraph_property	CSS プロパティ値でセレクターを検索
cssgraph_files	インデックス化されたスタイルファイルのツリー
cssgraph_status	インデックスの健全性チェック

---

補完ツール：cssprobe-cli

cssgraph は静的解析ツールです。ソースコードを読み込み、クラスがどこで定義されているか、何がその上にカスケードされるか、変更がどこに影響するかを回答します。ページがブラウザーで実際にどう表示されるか（オーバーフロー、スクロールチェーン、計算済み高さのチェーン、包含ブロックの乗っ取り）といったランタイムの質問には、実際のブラウザーを開いて計算済みスタイルと DOM メトリクスを読み取る cssprobe-cli を使用してください。この 2 つのツールは互いを補完します。

	cssgraph（静的）	cssprobe-cli（ランタイム）
解析対象	ソースコード（CSS/SCSS/Less + JSX/TSX + テンプレート）	実際のブラウザー（計算済みスタイル + DOM）
回答内容	クラスの定義場所、カスケード、影響、未使用の CSS	実際のレンダリングレイアウト、オーバーフロー、スクロール、高さのチェーン
使用タイミング	ブラウザーを使う前、または使わずに	静的解析の後、ランタイムで検証するとき
使用方法	cssgraph init + explore/rule/impact	open + inspect/layout/findings

スタイルの問題に推奨されるワークフロー — まず静的解析を行い、その後ランタイムで検証します。

# 1. Static: find the definitions, cascade, and blast radius (cssgraph)
cssgraph explore .btn-primary
cssgraph cascade .btn-primary

# 2. Runtime: confirm what actually renders (cssprobe-cli)
npm i -g cssprobe-cli
cssprobe-cli open https://example.com
cssprobe-cli inspect .btn-primary
cssprobe-cli findings .btn-primary

インストール：npm install -g cssprobe-cli（Node.js >= 22.5.0 が必要です）。npm / GitHub をご覧ください。

---

対応言語

言語	拡張子	抽出方法
CSS	.css	PostCSS 標準
SCSS	.scss	postcss-scss プラグイン
Less	.less	postcss-less プラグイン
Sass（インデント形式）	.sass	コンパイル → PostCSS
PostCSS カスタム	.pcss	PostCSS 標準
JSX / TSX	.jsx .tsx	className + CSS-in-JS
JavaScript / TypeScript	.js .ts .es6	className + CSS Modules
ERB（Rails）	.erb	class="..." の抽出
Haml（Rails）	.haml	.classname + {:class =>} の抽出
HTML	.html	class="..." の抽出
CSS Modules	.module.css .module.scss .module.less	動的インポートの解決
Tailwind	tailwind.config.js + CSS @theme	v3 JS 設定 + v4 CSS 設定

---

本番環境での規模

プロジェクト	合計ファイル数	初回インデックス作成	ノード	エッジ
小規模	~50	~15s	~16K	~50K
本番環境のモノレポ	~11K	~3-5m	~780K	~22M

---

プロジェクト設定

デフォルトでは設定不要です。任意でプロジェクトのルートに .cssgraph.json を配置できます。

{
  "exclude": ["static/vendor/", "**/legacy/**"],
  "extensions": {
    ".pcss": "css"
  }
}

組み込みのデフォルト除外設定（常に適用）：**/*.test.*、**/*.stories.*、**/*.spec.*、**/*.min.*、**/__tests__/**、**/__snapshots__/**、**/__mocks__/**、**/generated/**、**/spec/**、**/vendor/**。

---

対応プラットフォーム

プラットフォーム	アーキテクチャ	インストール
macOS	x64, arm64	npm
Linux	x64, arm64	npm
Windows	x64, arm64	npm

---

cssgraph が役に立ったら

⭐ のスターを付けると、ほかの開発者が見つけやすくなり、開発を続ける励みにもなります。

---

ライセンス

MIT