cssprobe-cli

cssprobe-cli

実行時 CSS プローブ — ライブブラウザーでレイアウト、スクロール、色、背景、フォントなどを調査します。人間と AI エージェントの両方を対象にしています。

AI エージェント向けの静的 CSS 診断と実行時 CSS 診断 — cssgraph（CSS ナレッジグラフ）と組み合わせることで、全体像を把握できます。

---

cssprobe-cli を選ぶ理由

AI エージェントが CSS のデバッグ（この要素がはみ出すのはなぜか、実際に描画されたレイアウトはどうなっているか、このコンテナーはスクロール可能かなど）を行う際、ブラウザーを見ることはできません。静的コードから推測するため、はみ出し、スクロールチェーン、包含ブロックの乗っ取りといった、実行時にしか発生しない問題を見落とします。

cssprobe-cli はエージェントに目を与えます。 実際のブラウザーを起動し、挿入した JavaScript を使って計算済みスタイルとメトリクスを収集し、信頼度モデルで分析して、構造化された調査結果を 1 つのコマンドで返します。エージェントが任意のセレクターについて質問すると、ターミナルを離れることなく、DOM ツリー、ASCII レイアウト図、はみ出しの警告、スクロール診断を取得できます。

---

インストール

人間向け

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

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

または、インストールガイドをお読みください。ただし、正直なところ、エージェントに任せてください。人間は設定を入力し間違えがちです。

LLM エージェント向け

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

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

または、直接インストールしてください。

npm install -g cssprobe-cli
cssprobe-cli skill-install

---

動作の仕組み

┌───────────────────────────────────────────────────────────┐
│                      AI Agent                              │
│                                                           │
│  "Is .sidebar overflowing?"                               │
│      calls: cssprobe-cli inspect .sidebar                 │
│                             │                             │
└─────────────────────────────┬─────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────┐
│                  cssprobe-cli daemon                       │
│                                                           │
│  collector (IIFE) → analyzer (pure) → renderer (md/json)  │
│                             │                             │
│                             ▼                             │
│               Playwright browser (Chromium)                │
│     getBoundingClientRect · getComputedStyle · DOM walk    │
└───────────────────────────────────────────────────────────┘

1. セッション — open はブラウザーを管理するデーモンプロセスを起動します。コマンドは Unix ソケット経由で接続します。
2. コレクター — IIFE としてページに挿入されます。DOM をたどり、計算済みスタイル、宣言値、要素のメトリクスを読み取ります。
3. アナライザー — 純粋な Node.js 関数です。信頼度レベル（DEFINITE / INDEFINITE / UNVERIFIABLE）で調査結果を分類します。
4. レンダラー — Markdown（デフォルト）または JSON を出力します。ASCII レイアウト図、DOM ツリー、調査結果が含まれます。

---

クイックスタート

1. ページを調査する

# Open browser (non-blocking, starts daemon session)
cssprobe-cli open https://getbootstrap.com/docs/5.3/examples/checkout

# Inspect with CSS selector
cssprobe-cli inspect .container

# Show ASCII layout diagram
cssprobe-cli layout .container

# Show only issues/warnings
cssprobe-cli findings .container

# Close browser when done
cssprobe-cli close

2. ログインが必要なページ

# Open browser in headed mode
cssprobe-cli open https://mysite.com --headed

# User manually logs in...

# Save session state for future use
cssprobe-cli state-save --name mysite

# Reopen with saved state (no login needed)
cssprobe-cli open https://mysite.com --state state.json --headed

3. JSON 出力

cssprobe-cli inspect body --json
cssprobe-cli inspect body --json | jq '.findings[] | {id, confidence, message}'

4. MCP サーバーとして使用する（AI クライアント）

cssprobe-cli には MCP サーバー（stdio）が付属しているため、AI クライアントはシェルを使わず、ネイティブツールとして呼び出せます。

cssprobe-cli mcp-install          # auto-detect and configure installed clients
cssprobe-cli mcp-install --target=claude,cursor,codex
cssprobe-cli mcp-install --local  # write project-scoped config

任意の MCP クライアント向けの手動設定：

{
  "mcpServers": {
    "cssprobe-cli": { "command": "cssprobe-cli", "args": ["mcp"] }
  }
}

次の 10 個のツールを公開します：cssprobe_open、cssprobe_inspect、cssprobe_tree、cssprobe_layout、 cssprobe_findings、cssprobe_eval、cssprobe_screenshot、cssprobe_inject_css、 cssprobe_close、cssprobe_status。cssprobe-cli mcp-uninstall で削除できます。

---

コマンド

セッション管理

コマンド	説明
open [url]	セッションモードでブラウザーを開く（ノンブロッキング）
open [url] --headed	ブラウザーウィンドウを表示する
open [url] --state <file>	保存済みの Cookie と localStorage を使って開く
open [url] --viewport 1280x720	ビューポートサイズを指定する
open [url] --expect-url <regex>	最終 URL がパターンに一致しない場合に失敗する
open [url] --fail-on-login	ログイン URL にリダイレクトされた場合、すぐに失敗する
close	ブラウザーセッションを閉じる
close --all	すべてのワークスペースのセッションを閉じる
status	セッションの状態（URL、タイトル、フレーム数）を表示する
frames	フレームのインデックス、名前、URL、メインフレームのマーカーを一覧表示する
doctor	ブラウザーのインストール状況と Playwright の想定リビジョンを診断する

CSS の検査

コマンド	説明
inspect <selector>	CSS の完全な診断（計算値、宣言値、検出事項）
inspect <selector> --layout	ASCII レイアウト図を含めます
inspect <selector> --brief	簡潔な形式：ツリーの概要と警告／エラーのみ
inspect <selector> --json	構造化された JSON 出力
tree <selector>	DOM ツリー構造
layout <selector>	ASCII レイアウト図
findings <selector>	問題／警告／エラーのみ

検査コマンドでは、対象の iframe を指定するために --frame <index|name|url-substring> を指定できます。デフォルトではメインフレームが対象です。

CSS の挿入

コマンド	説明
inject-css <css>	現在のページに CSS を挿入

ブラウザー

コマンド	説明
resize <width> <height>	ブラウザーのビューポートをリサイズ
eval <expression>	JavaScript を評価（ブラウザーコンテキスト）。DOM ノードは自動的にシリアライズされ、Promise は待機されます。undefined のフィールドは null になります
eval @file / eval -	ファイルまたは標準入力から式を読み込み
playwright <call>	Playwright API を実行（Node.js コンテキスト）
screenshot	スクリーンショットを撮影（~/.cssprobe-cli/screenshots/ に保存。--out で保存先を変更）

操作

コマンド	説明
click <selector>	実際のマウスクリック（自動スクロールと操作可能状態になるまでの待機。カスタム React コンポーネントにも対応）
hover <selector>	実際のマウスホバー
type <selector> <text>	テキストを入力（値を置換）。送信するには --press Enter、実際のキーイベントを発生させるには --sequential を指定
wait-for <selector>	セレクターの状態を待機（--state visible|hidden|attached|detached、--timeout ms）
wait-for --js "<predicate>"	JS の述語が true になるまで待機
wait-for --network-idle	ページがネットワークアイドル状態になるまで待機（ページレベル。--frame は指定不可）
wait-for ... --frame <spec>	iframe 内で待機（selector／js モード）
sample "<expr>"	式を一定時間サンプリング（--interval、--duration、--key、--frame）。タイムラインと概要を返します
wait-stable "<expr>"	式の変化が止まるまで待機（--tolerance、--window、--timeout）
run <file>	複数ステップのフロースクリプトを実行

click／hover は --nth N（1 始まり。デフォルトは最初の一致）、--force（操作可能状態の確認を省略）、--timeout ms に対応しています。--nth を指定せずに複数の要素が一致した場合、誤った対象をクリックしないよう処理は失敗します（厳密モード）。

状態

コマンド	説明
state-import <file>	Netscape 形式の Cookie をインポート
state-save	現在のブラウザーセッション状態（Cookie と localStorage）を保存
state-check	状態ファイルを検証：Cookie 数、有効期限、対象ドメインのカバレッジ（--state、--url）

設定

コマンド	説明
config-show	現在の設定を表示
config-set <key> <value>	設定値を設定
config-list	すべてのプロファイルを一覧表示
config-use <name>	アクティブなプロファイルを切り替え
config-new <name>	新しいプロファイルを作成
config-path	設定ファイルのパスを表示

---

複数ステップのフロー

操作コマンドでページをステップごとに操作します。run を使うと、一連の操作をバージョン管理可能なスクリプトにできます。

cssprobe-cli open https://example.com/editor
cssprobe-cli wait-for .editor-canvas
cssprobe-cli click ".layout-switch" --nth 1
cssprobe-cli type ".block-title input" "Hello" --press Enter
cssprobe-cli inspect .block-grid --json
cssprobe-cli close

繰り返し実行するフローでは、スクリプトを作成し、1 つのコマンドで実行します。スクリプトはデーモンセッション内で実行されます（Playwright の page に完全にアクセスできます）。

// flow.js
export default async ({ page, context, frames, newPage, click, waitFor, type, inspect, screenshot, expect, log }) => {
  await page.goto('https://example.com/editor', { waitUntil: 'domcontentloaded' });
  await waitFor('.editor-canvas', { state: 'visible', timeout: 10000 });

  await click('.layout-switch', { nth: 1 });
  await waitFor({ js: "() => document.body.dataset.layout === 'two-col'" });

  await type('.block-title input', 'Hello', { press: 'Enter', sequential: true, clear: true });
  await waitFor({ networkIdle: true });

  const { findings } = await inspect('.block-grid', { format: 'json' });
  log('findings:', findings.length);
  await screenshot({ path: './after-layout-switch.png' });

  return { findings: findings.length };
};

cssprobe-cli run ./flow.js        # --timeout ms for the whole script (default 300000, 0 = unlimited)

スクリプトでは、API オブジェクトを受け取る非同期関数を default-export する必要があります。API オブジェクトには、page、context、frames()、newPage()、click、hover、type、waitFor、inspect、screenshot、expect、log が含まれます。waitFor は { state, timeout, frame } を受け取ります。捕捉されなかったページエラーは、pageErrors として結果エンベロープに収集されます。screenshot の相対パスはスクリプトのディレクトリを基準に解決されます。ログ（log() と console.*）は収集され、結果とともに返されます。失敗時には、コマンドは 1 で終了し、収集されたログを出力して、セッションを維持します。

スクリプトは、完全な Node 権限を持つローカルデーモンによって実行されます。信頼できるスクリプトのみを実行してください。

---

シナリオスイート（回帰テスト）

JSON スイートから、繰り返し実行可能な回帰テストケースを実行します。各ケースで新しいブラウザーを開き、ステップを実行し、保存した値をアサートして、成果物とオプションの JUnit レポートを書き出します。

cssprobe-cli scenario run suites/ticket-26571394.json \
  --state ~/.cssprobe-cli/states/preprod.json \
  --artifacts out/ticket-26571394 \
  --junit out/junit.xml

{
  "name": "ticket 26571394 preprod",
  "defaults": { "viewport": { "width": 1280, "height": 800 } },
  "cases": [
    {
      "name": "refresh keeps the hash section aligned",
      "url": "https://example.com/#listen-to-tcmi",
      "steps": [
        { "do": "sample", "expression": "({ hash: location.hash, top: Math.round(document.querySelector('#listen-to-tcmi')?.getBoundingClientRect().top ?? -1) })", "interval": 250, "duration": 12000, "key": "top", "tailFrom": 9500, "save": "timeline" },
        { "do": "assert", "label": "hash retained", "on": "timeline", "path": "summary.last.value.hash", "eq": "#listen-to-tcmi" },
        { "do": "assert", "label": "anchor stable", "on": "timeline", "path": "summary.tail.min", "min": 70 },
        { "do": "assert", "label": "anchor stable", "on": "timeline", "path": "summary.tail.max", "max": 90 }
      ]
    },
    {
      "name": "deployment fingerprint",
      "url": "https://example.com/",
      "steps": [
        { "do": "waitFor", "js": "() => !!window.DEBUG?.NavigatorStore", "timeout": 20000 },
        { "do": "assert", "globals": { "DEBUG.NavigatorStore.setHashRestoreProtected": "function" }, "absent": ["DEBUG.NavigatorStore.navigateToSectionId"] }
      ]
    }
  ]
}

ステップ：goto、reload、wait、eval、sample、waitStable、click、waitFor、screenshot、assert。wait は固定の ms を指定します。waitFor は、iframe 内でセレクターまたは JavaScript を待機するための frame に対応しています。sample と eval は save: "<name>" で値を保存します。アサーションは on: "<name>" と path で保存済みの値を読み取るか、ライブの state（url、title、frames）、url、globals、absent を確認します。sample は key、tailFrom、ignoreErrors に対応しています。実行ごとに summary.json、ケースごとの case.json、サンプル系列、失敗時のスクリーンショットが書き出されます。

iframe とプレビューページ。 ページには非表示のヘルパー iframe（about:blank）が含まれることがあります。frames を使って実際のフレームを選択し、表示されていないフレーム要素を待つ場合は state: "attached" を使用してください。プレビューフレームの描画には 6～8 秒かかることがあり、分析リクエストによって networkIdle が完了しない場合があります。そのため、networkIdle の代わりに、固定の wait ステップの後でフレーム内の waitFor（frame: "i/preview"）を使うことをおすすめします。

信頼度モデル

各調査結果には信頼度レベルが付与されます。

レベル	意味
DEFINITE	計算値（getComputedStyle から取得した事実）またはアクセス可能な宣言値に基づいています
INDEFINITE	宣言値に % が使われており、実行時に解決されます
UNVERIFIABLE	宣言値がないか、クロスオリジンのためブロックされたスタイルシートに含まれています

レポートヘッダーには、次のように表示されます：confidence: DEFINITE 8 | INDEFINITE 0 | UNVERIFIABLE 1

---

補完ツール：cssgraph

cssprobe-cli は実行時の CSS プローブです。実際のブラウザーを開き、実際に描画された内容を読み取ります。ソースコードに関する静的な質問、たとえば .btn-primary の定義場所、適用されるカスケード、参照しているコンポーネント、編集した場合の変更点については、cssgraph を使用してください。これは、スタイルシート内のすべての className、プロパティ、変数、アットルールを格納したローカルの SQLite ナレッジグラフです。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)
cssprobe-cli open https://example.com
cssprobe-cli inspect .btn-primary
cssprobe-cli findings .btn-primary

インストール：npm install -g cssgraph（Node.js >= 22.5.0 が必要です）。12 個の MCP ツール（cssgraph_explore、cssgraph_rule、cssgraph_impact、…）と CLI コマンドを提供します。npm ／ GitHub を参照してください。

---

設定

# Set values
cssprobe-cli config-set browser chromium
cssprobe-cli config-set depth 8
cssprobe-cli config-set viewport 375x812

# Profile management
cssprobe-cli config-new staging
cssprobe-cli -p staging config-set browser firefox
cssprobe-cli config-use staging

優先順位：CLI フラグ > 環境変数 > 設定ファイル

--browser       CSSPROBE_BROWSER
--depth         CSSPROBE_DEPTH
--headed        CSSPROBE_HEADED
--viewport      CSSPROBE_VIEWPORT
-p, --profile   CSSPROBE_PROFILE

設定ファイル：~/.cssprobe-clirc

---

対応プラットフォーム

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

---

開発

npm install
npm run build       # tsc + esbuild collector + daemon entry + generate help.json
npm test            # Run unit tests (58 tests)
npx tsc --noEmit    # Type check only

cssprobe-cli が役に立った場合

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

---

ライセンス

MIT