pixelcheck

PixelCheck

フロントエンドを書く AI エージェントに、本物の目と手を。

すぐに導入できる MCP サーバー。5 つのブラウザプリミティブ。15 か国にまたがる18人のペルソナ。
ローカルファースト · ベンダー非依存 · MIT ライセンス · 自分のものにできます。

クイックスタート →  ·  プリミティブ  ·  MCP サーバー  ·  監査プリセット  ·  E2E テストではだめな理由  ·  変更履歴

---

PixelCheck が役に立ったら、スターを付けてください。プロジェクトを見つけてもらいやすくなります。

---

今、あなたはスクリーンショットを撮るだけの仲介役です。

AI エージェントはフロントエンドの80％を書いています。速く、コードを書くのが得意です。でも、目が見えません。

• ボタンを書きます。 正しく表示されるか確かめるために Chrome を開きます。スクリーンショットを貼り付けて、修正を頼みます。
• OAuth フローを調整します。 ひそかに壊れていないか確認するためにログインします。今月だけでも、もう6回目です。
• 日本語の文字列を更新します。 ユーザーから「ページの半分が英語のままです」とメールが届きます。見落としていました。
• チェックアウトを書き直します。 ステップ3が分かりにくいかどうかを実感するためだけに、iPhone、Android、iPad で操作してみます。
• アラビア語のレイアウトを変更します。 RTL が反映されず、2日間気づきません。

あなたが橋渡し役になります。エージェントには考えがあります。あなたにはブラウザがあります。この2つが出会うことはありません。 毎週、あなたの時間が何時間も、いつまでも費やされます。

PixelCheck が橋渡しをします。

単一の MCP サーバー。5つのプリミティブ。一度導入すれば、エージェントに目と手が備わります。

see(url, opts)              snapshot a page (DOM + screenshot + console + network)
act(url, steps)             execute an action sequence (semantic + selector + Computer Use)
extract(url, schema)        pull structured data matching a Zod / JSON schema
judge(url, rubric)          score a page against a rubric ("is this dark-pattern free?")
compare(a, b, criteria)     A/B comparison of two URLs (incl. blind mode)

これでエージェントがページを移動し、レンダリング済み HTML を見て、コンソールエラーを読み取り、クリックし、入力し、判断し、比較できるようになります。ワークフローから離れる必要はありません。~/.mcp.json に4行追加するだけで、Claude Desktop、Cursor、Cline、Continue、Zed、Claude Code に導入できます。

npm install -g pixelcheck        # browser binary auto-installs on install
pixelcheck doctor                # verify environment (--fix self-heals)
pixelcheck-mcp                   # MCP server (stdio transport)

// ~/.mcp.json
{
  "mcpServers": {
    "pixelcheck": {
      "command": "pixelcheck-mcp",
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

クライアントを再起動すれば、エージェントに目が備わります。

今後も変わらない3つの約束。

ローカルファースト。 PixelCheckはすべてお使いのマシン上で動作します。外部ネットワークへの接続先は、エージェントがすでに使用しているLLMプロバイダーだけです。スクリーンショット、DOM、ビジネスフロー、OAuthトークン、顧客のURLは、すべてお客様の手元に残ります。テレメトリーは一切ありません。リモートストレージもありません。SaaSへの登録も不要です。監査データがAnthropicに送信されるのは、ビジョンクリティックがスクリーンショットを積極的に評価するときだけで、初回実行時に一度だけオプトインします。

ベンダーに依存しません。 現在はClaudeで動作します。マルチプロバイダー抽象化（OpenAI、Gemini、Ollama-local）はv1.xのロードマップにあり、設定フラグを1つ変えるだけでエージェントを切り替えられます。理由はシンプルです。単一のLLMプロバイダーに縛るAIツールは、2026年には廃れていきます。PixelCheckはその解決策です。

自分のものとして所有できます。 MITライセンスです。ソースコードを利用できます。有料プランはありません。「Pro」へのアップグレードもありません。水面下で進む商用フォークもありません。このリポジトリにある1,858件のテスト、29件のADR、公開済みの30件のスキーマを備えた製品が、製品のすべてです。登録の壁の向こうにプレミアム版はありません。これまでも、これからもありません。

---

監査プリセット — 橋渡し役ではなく、あなた自身がユーザーになりたいときに

5つのプリミティブを組み合わせると、あなた自身が運用担当者であるとき、さらに強力なものになります。PixelCheckは、プリミティブに加えて18のペルソナ／15か国の監査プリセットを備えています。これはCLIファーストの構成で、デプロイのたびに「18人の実ユーザーがあなたの製品をレビュー」します。

デプロイする。テストは合格。CIも成功。しかし、その後に次のようなことが起こります。

• 日本のユーザーがアプリを開くと、UIに翻訳されていない英語の文字列が半分ほど混在している
• ナイジェリアの低価格Androidスマートフォンを使うユーザーは、ヒーロー画像の読み込みに12秒待たされる
• OAuthログインフローが、10回のデプロイのうち6回目となる今回も、何の通知もなく壊れる
• アラビア語版が左から右に表示され、レイアウト全体が使いものにならなくなる
• 「Trusted」スコアバッジは緑色なのに、コピーには「すぐに操作をやめてください」と表示される

E2Eテストでは、こうしたことは検出できません。 E2Eテストが検証するのは、コードが実行されるかどうかです。現実の状況で、現実の人々にとって製品が使えるかどうかは検証しません。

監査プリセットは、17か国から18種類のユーザーとして実際のChromiumブラウザーを起動し、製品の主要なフローをたどって判定結果を出します。すべてのデプロイを、あらゆる言語、あらゆるデバイスクラスでシニアPM、QAエンジニア、UXレビュアーが監査するようなものです。

pixelcheck init projects/my-app --name "My App" --url "https://myapp.com"
pixelcheck run --project projects/my-app

出力：ステップごとのスクリーンショット、動画録画、ネットワークログ、WCAGアクセシビリティ違反、6つの評価軸にわたるAI採点結果を含む構造化レポートを、JSON、HTMLダッシュボード、またはMarkdownで提供します。

仕組み

各**（ペルソナ x シナリオ）**の組み合わせについて、次を行います。

 1. Launch Chromium with device-accurate fingerprint
    (viewport, locale, timezone, UA, regional proxy)
                        |
 2. Execute scenario steps semantically via Stagehand 3.x
    ("click the sign-up button" not "click #btn-37")
                        |
 3. 5-Layer Reliability Stack ensures 98%+ step success
    Stability Gate -> LLM Rewrite -> Selector Discovery -> Auto Selector -> Computer Use
                        |
 4. Claude Vision Critic + axe-core score each checkpoint on 18 dimensions
    completion | localization | visual_polish | trust_signals | accessibility | ...
                        |
 5. Critical steps escalate to Computer Use for pixel-level review
                        |
 6. Generate report: JSON + HTML dashboard + Markdown + video + HAR

E2Eテストではいけないのですか？

	従来のE2E	PixelCheck（監査プリセット）
テスト対象	コードのロジック	製品の利用体験
意思決定	ハードコードされたセレクター	AIが人間のようにページを読み取る
アサーションの形式	expect(text).toBe("Welcome")	「日本の無料プランユーザーにとって、このCTAは明確で、完全にローカライズされていますか？」
UIが変更された場合	セレクターが壊れ、テストが失敗する	セマンティックな指示が自動で適応する
失敗時の出力	スタックトレース	スクリーンショット＋動画＋6軸スコア＋具体的なUX上の問題
検出できるもの	機能上のバグ	i18nの抜け、UX上の摩擦、視覚的なリグレッション、信頼性の問題、アクセシビリティ違反、文化的な不一致

PixelCheckの監査プリセットは、E2Eテストの代替ではありません。 E2Eテストの後に実行するものです。「コードが動く」と「製品として優れている」の間を埋めるレイヤーです。

既存ツールとの比較

	PixelCheck	Playwright	Cypress	Stagehand	Browserbase
すぐに使える MCP サーバー	✅	❌	❌	❌	❌
AI エージェントが呼び出せるブラウザーのプリミティブ	5（see / act / extract / judge / compare）	該当なし（低レベルのページ API）	該当なし	3（act / extract / observe）	該当なし
AI ビジョン（judge / critique）	✅ Anthropic 経由	❌	❌	❌（操作のみ）	❌
組み込みペルソナ	15 か国にわたる 18 種類	❌	❌	❌	❌
ローカライズされたレポート（5 言語）	✅	❌	❌	❌	❌
WCAG 2.x 監査 + SARIF エクスポート	✅（axe-core + GitHub Code Scanning 対応）	プラグインを使った手動対応	プラグインを使った手動対応	❌	❌
デフォルトでローカルファースト	✅（お使いのマシン、お使いの API キー）	✅	✅	✅（または Browserbase）	❌（クラウドのみ）
ベンダーロックイン	なし（MIT、SaaS なし）	なし	なし	Browserbase は任意	完全にロックイン（有料 SaaS）
LLM プロバイダー	任意のものに切り替え可能（デフォルトは Anthropic。プリミティブはベンダーに依存しません）	該当なし	該当なし	任意のものに切り替え可能	該当なし
オープンソース	✅ MIT	✅ Apache 2.0	✅ MIT	✅ MIT	一部

要約：Playwright / Cypress は決定論的なブラウザードライバーです。何をクリックするかを正確に指定します。Stagehand は Playwright を自然言語の act / extract でラップし、エージェントがブラウザーを操作できるようにします。PixelCheck はさらに上位のレイヤーです。操作（act / extract）に加えて、あらゆる AI エージェントにビジョン（see / judge / compare）を提供する MCP 形式のインターフェースで、複数のペルソナを組み合わせた監査プリセットを備えています。ユニットテスト形式のテストには Playwright、エージェントにフォーム入力だけをさせる場合は Stagehand、UI を操作するだけでなく評価させる必要がある場合は PixelCheck を使ってください。

ペルソナ

実際のユーザーの多様性を網羅する、18 種類の組み込みペルソナがあります。購読プラン列は、ペルソナが監査対象の SaaS で利用している購読プラン（無料ユーザー / Pro 購読者 / パワーユーザー / エンタープライズ）を示します。これは、PixelCheck が製品のプラン別機能（ペイウォール、アップセル、アクセス制限付き UI、Pro 専用のフロー）を監査できるようにするためのものです。PixelCheck 自体は MIT ライセンスで、完全に無料です。有料プランや商用フォークはありません。

ペルソナ	国	言語	デバイス	購読プラン（アプリ内）
米国の大学生	US	英語	iPhone 14	Free
東京の主婦	JP	日本語	MacBook Pro	Pro
ベルリンのセキュリティアナリスト	DE	ドイツ語	iPad Pro	Power
上海の学生	CN	中国語	Xiaomi Android	Free
サンパウロのフリーランサー	BR	ポルトガル語	デスクトップ	Free
リヤドのビジネスマン	SA	アラビア語（RTL）	iPhone 15 Pro	Pro
ムンバイの会社員	IN	ヒンディー語	低価格 Android	Free
ソウルのデザイナー	KR	韓国語	QHD デスクトップ	Pro
ハノイの学生	VN	ベトナム語	Android	Free
モスクワのエンジニア	RU	ロシア語（キリル文字）	Windows デスクトップ	Free
ラゴスの起業家	NG	英語	低価格 Tecno	Free
メキシコシティの教師	MX	スペイン語（LATAM）	Android	Free
ジャカルタのギグワーカー	ID	インドネシア語	Android	Free
米国の退職した教師（72 歳）	US	英語	iPad	Free
ロンドンのセキュリティアナリスト	UK	英語	デスクトップ	Power
パリのマーケティングマネージャー	FR	フランス語	iPhone	Free
バンコクの学生	TH	タイ語	iPhone SE	Free
台北のエンジニア	TW	繁体字中国語	iPad	Pro

各ペルソナには、メンタルモデル（どのような人物で、何を期待するか）と重要な懸念事項（何が信頼を失わせるか）が含まれています。AI レビュアーは、ユーザーの製品をペルソナの視点から評価します。

6 種類の文字体系：ラテン文字、CJK、アラビア文字（RTL）、キリル文字、デーヴァナーガリー文字、タイ文字。

シナリオは宣言型 YAML

コードは不要です。クリック方法ではなく、ユーザーが行うことを記述します。

id: signup-flow
name: New User Signup
priority: P0
steps:
  - id: open-home
    type: visit
    url: https://myapp.com/${persona.url_locale}

  - id: click-signup
    type: act
    instruction: Click the sign-up or get-started button

  - id: check-language
    type: assert_visual
    instruction: |
      Is all visible text in ${persona.language}?
      Flag any English strings outside of brand names.

  - id: complete-oauth
    type: act
    instruction: Sign in with Google

  - id: verify-email
    type: check_email
    subject_contains: "welcome"
    timeout: 60000

  - id: a11y-check
    type: assert_a11y
    standard: wcag2aa          # axe-core WCAG analysis
    exclude: [".cookie-banner"]

  - id: rate-onboarding
    type: assert_visual
    critical_review: true    # escalates to Computer Use
    instruction: |
      Rate the post-signup experience. Is the value proposition
      clear within 10 seconds? Is the first action obvious?

12 種類のステップ：visit、act、extract、observe、wait_for、assert_visual、assert_dom、assert_a11y、check_email、screenshot、computer_use、custom

5層の信頼性スタック

AI駆動型ブラウザーは不安定です（ベースラインで約75％）。私たちはこれを解消しました。

Layer 1: Page Stability Gate                              +10%  (zero cost)
         Wait for network idle + DOM stable + framework hydration
                            |
Layer 2: LLM Rewrite + Local Mutation                     +7%   (~$0.001/call)
         Haiku rewrites failed instructions using DOM context;
         local rules rephrase/decompose/specify as fallback
                            |
Layer 3a: Selector Hint                                   +3%   (zero cost)
          Optional CSS selector fallback (manual or YAML-defined)
                            |
Layer 3b: Auto Selector Discovery                         +3%   (zero cost)
          Stagehand observe() extracts candidate selectors automatically
                            |
Layer 4: Computer Use Fallback                            +2-4% ($0.01-0.15/call)
         Claude sees the actual pixels and operates the browser directly
         (Sonnet for non-critical steps, Opus for critical reviews)

目標：すべてのペルソナ／シナリオの組み合わせで、**ステップ成功率98～99％**を達成します。

各ステップでは、execution_method に成功したレイヤーが記録されるため、実行ごとの信頼性の内訳を確認できます。

レポート

各監査では、証拠一式が生成されます。

reports/2026-04-11_post-deploy/
 |-- audit.json              # Machine-readable, all scores and issues
 |-- audit.html              # Dark-theme dashboard with trend sparklines
 |-- audit-explorer.html     # Filterable SPA view of every (scenario × persona) — open with ?lang=zh-CN/ja/es/de for localised UI chrome
 |-- audit.pdf               # Stakeholder-facing summary (A4, 12pt, vector text)
 |-- summary.md              # Terminal-friendly overview
 |-- jp-japanese-pro-desktop__signup-flow/
      |-- 01-open_home.png          # Timestamped screenshot
      |-- 02-check_language.png     # + SHA-256 hash for each
      |-- network.har               # Full network log
      |-- console.log               # Browser console errors
      |-- video/*.webm              # Session recording

audit.json とすべての MCP ツールのレスポンスには、トップレベルに schema_version フィールド（SemVer）が含まれます。仕様は docs/contracts/RESULT_SCHEMA.md に記載されています。機械可読な JSON Schema は docs/schemas/ にあり、npm run schemas で再生成できます。

WCAG 準拠レポート

assert_a11y シナリオステップでは、axe-core を実行してアクセシビリティ違反を検出します。v1 では、すべての違反に構造化された WCAG の情報が付与され、すべての関係者向けレポートに反映されます。

• PDF レポート — 適合レベル（A／AA／AAA）別、WCAG の4つの原則（知覚可能／操作可能／理解可能／堅牢）別にまとめた「WCAG Compliance Summary」セクションと、W3C の Understanding ドキュメントへの詳細リンク付きの違反基準トップ一覧表を掲載します。
• SARIF（GitHub Code Scanning／GitLab SAST） — wcag/1-4-3 や wcag/2-1-1 のように、基準ごとの ruleId を使用します。Security タブで W3C の条項を直接指定して絞り込めます。各ルールの詳細パネルには、「WCAG 1.4.3 Contrast (Minimum) (Level AA)」と W3C 仕様へのリンクが表示されます。
• audit.json — すべてのアクセシビリティに関する問題に、既存の description／recommendation と並んで wcag_level および wcag_criterion フィールドが追加されます。

カタログは、本番環境に導入されている標準である WCAG 2.1 に加え、WCAG 2.2 で新たに追加された9つの成功基準（例：2.4.11 フォーカスの遮蔽なし、2.5.8 ターゲットサイズ）を網羅しています。レポートを zh-CN／ja／es／de で読むコンプライアンスチーム向けには、セクション見出しが翻訳されます。SC 名と ID 番号（1.4.3、2.1.1）は、コンプライアンス文書との一貫性を保つため、標準表記のままです。

使用例 — 「WCAG 2.1 AA に準拠していますか？」と尋ねる RFP への回答：

pixelcheck run --project myapp                                    # writes audit.pdf + audit.sarif
# Open audit.pdf → "WCAG Compliance Summary" section shows A / AA / AAA counts
# Or upload audit.sarif via github/codeql-action/upload-sarif → grouped under wcag/* ruleIds

設計の詳細については、ADR-024 を参照してください。

レポートのローカライズ

関係者向けレポート（PDF／トレンドダッシュボード／PR 差分 Markdown／PR 差分 HTML）は、対象者の言語で出力されます。v1 では5つのロケールに対応しています。

コード	言語	使用対象
en	英語（デフォルト）	基準
zh-CN	簡体字中国語	中国市場のチーム
ja	日本語	日本市場のプロダクト組織
es	スペイン語	スペインおよびラテンアメリカ
de	ドイツ語	DACH 地域の企業

pixelcheck run --project myapp --locale ja          # Japanese PDF + reports
pixelcheck trends --project myapp --locale zh-CN     # Chinese trends dashboard
pixelcheck diff <a> <b> --format markdown --locale es  # Spanish PR comment

または、config.yaml でデフォルトを固定できます。

project_name: myapp
base_url: https://myapp.com
default_locale: ja    # any audit run on this project defaults to ja

翻訳対象：レポートの骨組み — セクションタイトル、表の見出し、ステータス／重大度バッジ、免責事項の文章。翻訳対象外：PixelCheck の検出内容（Claude に指定した言語で LLM が生成するため）と、数値／日付／実行 ID です。設計の詳細については、ADR-023 を参照してください。

翻訳のレビュー状況：機械翻訳を用いたドラフトで、ネイティブスピーカーによるレビュー待ちです。レビュー担当者への謝辞は公開しており、docs/translation-review-template.md および翻訳レビュー用 Issue テンプレートをご覧ください。v1.x のレビューが完了次第、確認済みのレビュー担当者を以下に掲載します。

ロケール	レビュー担当者	日付	適用した修正
en	（原文 — レビュー不要）	—	—
zh-CN	保留中	保留中	保留中
ja	保留中	保留中	保留中
es	保留中	保留中	保留中
de	保留中	保留中	保留中

PDF レポート（audit.pdf）

エンジニアリング部門の上層にいる意思決定者、つまり PM、経営幹部、顧客、営業／CS 担当者向けの、A4 縦向き・4 セクション構成の PDF です。メールクライアントでインライン表示され、スライドデッキに埋め込めて、スマートフォンで開ける形式です。

セクション	内容
表紙	プロジェクト名 + URL + 実行日 + 色分けされた総合スコア（緑 ≥ 8、アンバー 5–8、赤 < 5）+ 7 カウンターのサマリーカード
主な指摘事項	重大度順（critical → high → medium → low）、最大 5 件。それぞれにシナリオ × ペルソナのコンテキスト + 推奨事項を記載
シナリオ結果	シナリオ × ペルソナごとに 1 ブロック：ステータスバッジ、スコア + コスト、ディメンション別テーブル、すべての問題
方法論	監査の仕組み、ペルソナ一覧、シナリオ一覧、評価基準に関する免責事項、アーカイブ用の実行 ID

ベクターテキスト（選択可能／検索可能／アクセシブル）であり、HTML のスクリーンショットではありません。スクリーンショットを埋め込まないため、ファイルサイズは約 1 MB 未満に収まり、メールで送信できます。視覚的な証拠を確認する場合は、受信者が audit-explorer.html を開きます（方法論の免責事項に記載）。

デフォルト：毎回の実行で ON です。ローカルでの高速な反復時にスキップするには --no-pdf を渡します。設計の詳細については、ADR-020 を参照してください。

過去の傾向

スコアはローカルの SQLite データベースに記録されます。履歴の確認方法は 3 つあります。

pixelcheck history                    # Terminal table of recent runs with scores
pixelcheck diff run_0412 run_0411     # Score deltas, new/resolved issues
pixelcheck trends                     # Full HTML dashboard with 5 charts (writes <reports>/trends.html)

pixelcheck trends は <reports>/history.db を読み込み、「UX は改善したか、悪化したか？」に答えるスタンドアロンの HTML ダッシュボードを出力します。インライン SVG チャートが 5 つあります（Chart.js／外部 CDN 不使用。ファイアウォールの内側でも開け、メール送信／印刷／アーカイブも問題なく行えます）。

チャート	わかること
総合スコアの折れ線グラフ	上昇傾向か、下降傾向か？
Pass／Warn／Fail の積み上げ棒グラフ	安定しているか、不安定か？
経時的な問題数（合計 + 重大）	リグレッションが集中しているのはどこか？
経時的なコスト	効率が低下していないか？
ディメンション別の複数折れ線グラフ	どの評価ディメンションが原因か？

さらに、上部に 6 つのサマリーカード（最新スコア、直近 7 回の平均、直近 30 回の平均、総コスト、問題の総数、重大な問題の総数）と、ナビゲーション用の最近の実行一覧テーブルがあります。設計の詳細については、ADR-021 を参照してください。

pixelcheck trends --project myapp -n 90 --dashboard reports/trends.html

実行ごとの audit.html にもインラインのスパークラインチャートが含まれており、そのレポート内で傾向をひと目で確認できます。

品質ゲート

エクスペリエンスが設定した基準を下回った場合に、CI ビルドを失敗させます。

pixelcheck run --project projects/my-app --min-score 7.5
# Exit code 1 if overall score < 7.5

クイックスタート

1. インストール

npm install pixelcheck

pixelcheck が必要とするブラウザーバイナリ（Chrome Headless Shell）は、postinstall ステップで自動的に取得されます。CI、--ignore-scripts、オフライン環境、PIXELCHECK_SKIP_BROWSER_DOWNLOAD=1 などの理由でスキップされた場合は、必要に応じて次のコマンドで取得してください。

npx pixelcheck install            # headless audits (default)
npx pixelcheck install --headed   # also fetch full Chromium for --headed runs

npx playwright install を単独で実行する必要はありません。pixelcheck は実行時に使用するものとまったく同じリビジョンのブラウザーをインストールします（単独でインストールすると、異なるリビジョンが取得される場合があります）。ブラウザーが見つからない場合も、初回の run／explore 時に自動修復され、pixelcheck doctor --fix を実行すれば直接ダウンロードされます。

企業プロキシ／Alpine Linux／Docker／エアギャップ環境については、 docs/INSTALLATION.md を参照してください。

2. 環境を確認する

npx pixelcheck doctor

Node のバージョン、API キー、設定／シナリオ／ペルソナ、ネットワークプロキシ、api.anthropic.com への接続可否を報告します。準備ができていれば終了コード 0、いずれかのチェックに失敗した場合は 1 で終了します。監査を実行する前に問題を検出して停止する CI スクリプトで役立ちます。

診断の詳細を表示するには --verbose を追加し、オフライン／エアギャップ環境では --skip-network を指定します。

3. プロジェクトをセットアップする（対話形式またはスクリプト）

対話形式のウィザード（初めて使用する場合に推奨）：

npx pixelcheck init
# Walks you through project name, base URL, sample scenario, and runs
# `doctor` at the end to confirm setup.

非対話形式（CI／スクリプト）：

npx pixelcheck init my-project --name acme-shop --url https://acme.example.com

どちらの方法でも、次のファイルが作成されます。

• config.yaml（プロジェクト名 + ベース URL + モデルのデフォルト設定 + 予算）
• scenarios/00-smoke.yaml（ビジュアル + アクセシビリティチェックのスターター）

4. API キーを設定する

export ANTHROPIC_API_KEY=sk-ant-...

console.anthropic.com でキーを取得してください。上記のウィザードでキーが設定されていない場合は通知されます。pixelcheck doctor でもいつでも再確認できます。

5. 最初の監査を作成する

npx pixelcheck init projects/my-app --name "My App" --url "https://myapp.com"

これにより、設定ファイルとスターターシナリオを含むプロジェクトディレクトリが生成されます。シナリオを編集して、アプリのフローに合わせてください。

6. 実行する

# Dry run — validate config, print the persona x scenario matrix
npx pixelcheck run --project projects/my-app --dry-run

# Full audit
npx pixelcheck run --project projects/my-app

# Debug mode — visible browser
npx pixelcheck run --project projects/my-app --headed

# Single persona
npx pixelcheck run --project projects/my-app --persona jp-japanese-pro-desktop

CI との連携

デプロイのたびに監査を実行します。

# .github/workflows/deploy.yml
audit-after-deploy:
  needs: [deploy]
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    # CI sets CI=true, which skips the auto browser-download; fetch it explicitly.
    - run: npm install pixelcheck && npx pixelcheck install
    - run: npx pixelcheck run --project .audit --min-score 7.0
      env:
        ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    - uses: actions/upload-artifact@v4
      if: always()
      with:
        name: audit-report
        path: reports/

または、すべてのプロジェクトを監査する中央の PixelCheck リポジトリにディスパッチします。

    - run: |
        gh workflow run post-deploy-audit.yml \
          --repo your-org/pixelcheck \
          --field project="my-app"
      env:
        GH_TOKEN: ${{ secrets.GH_PAT }}

終了コード：0 = 合格、1 = 不合格、2 = 警告。

CI 出力形式

PixelCheck は CI 環境（CI=true、GITHUB_ACTIONS=true、GITLAB_CI=true、CIRCLECI=true、TF_BUILD=True、または JENKINS_URL）を検出すると、audit.json／audit.html とともに、4 つの標準形式を自動的に出力します。

ファイル	形式	利用先
junit.xml	JUnit XML	Jenkins、GitLab CI、Azure DevOps、CircleCI
audit.sarif	SARIF 2.1.0	GitHub Code Scanning、GitLab SAST
audit.jsonl	JSON Lines（1 行につき 1 レコード）	jq、ログ集約ツール、カスタムダッシュボード
github-annotations.txt	GHA ワークフローコマンド	GitHub Actions のインライン PR アノテーション

GitHub Actions 内では、ワークフローコマンドの各行も stderr にストリーミングされるため、別途アノテーションのステップを設けなくても、問題を PR の差分にインラインで表示できます。

動作を明示的に上書きします。

• --ci-format auto — デフォルト。CI では 4 形式すべてを出力し、開発者のノート PC では出力しません
• --ci-format all — 環境に関係なく 4 形式すべてを強制的に出力します
• --ci-format none — CI 形式の出力をスキップします
• --ci-format junit,sarif — カンマ区切りで形式を指定します

重大度の対応付け：critical／high → SARIF error ／ GHA error、medium → warning／warning、low → note／notice。ADR-019 で設計の詳細を確認できます。

例 — SARIF を GitHub Code Scanning にアップロードする場合：

- run: npx pixelcheck run --project .audit
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: reports/<run-id>/audit.sarif

PR 差分レポート

「この PR によって UX は改善したか、悪化したか？」という概要を PR コメントとして投稿するには、次の 2 つのコマンドを実行します。

# Audit main → audit PR → diff → post
- run: pixelcheck run --tag main && pixelcheck run --tag pr
- run: pixelcheck diff <MAIN_RUN_ID> <PR_RUN_ID> --format markdown --output diff.md
- uses: marocchino/sticky-pull-request-comment@v2
  with: { path: diff.md }

Markdown には次の内容が含まれます。

• 指標の見出しテーブル（総合スコア／問題／重大な問題／コスト／所要時間）と、増減を示す ▲ ／ ▼ の矢印
• 寸法ごとの変化（差分の絶対値が大きい順）
• 🆕 この PR で新たに発生した問題（重大度タグと推奨事項付き）
• ✅ この PR で修正された問題
• 両方の一覧が空の場合の「意味のある UX の変化はありません」というメッセージ

その他の出力形式：メール／Slack 向けの --format html、後続のグラフ作成向けの --format json、ターミナル向けの --format text（デフォルト）。--output <path> を使用するとファイルに直接書き込みます（拡張子から形式を自動判定）。省略すると stdout に出力します。ADR-022 で設計の詳細を確認できます。

通知：完了時に Slack の Webhook と Telegram ボットで通知します。

MCP サーバー

PixelCheck には MCP サーバーが付属しており、任意の Model Context Protocol クライアント（Claude Code、Cursor、Cline、Continue、Zed agent）から、ワークフローを離れることなく監査を実行できます。

Claude Code に登録する

~/.mcp.json（またはクライアントに対応する設定ファイル）に追加します。

{
  "mcpServers": {
    "pixelcheck": {
      "command": "pixelcheck-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

ツール

ツール	種類	使用する場面
audit_url	プリセット	1 つの URL に対して、エージェントループ、スコアリング、JSON および HTML レポートを含む監査パイプライン全体を実行したい場合。
explore_url	プリセット	自由形式の目標で手早く自律実行したい場合。シナリオ YAML は不要です。
see	プリミティブ	URL を一度確認し、DOM の概要、スクリーンショット、コンソールエラー、および任意の自然言語メモを取得したい場合。goal を省略すると LLM コストは 0 です。
act	プリミティブ	一連の操作（クリック／入力／スクロール／スクリーンショット／自然言語の act／ビジョンの note）を実行し、各ステップの状態と最終 DOM、スクリーンショットを取得したい場合。
extract	プリミティブ	URL から、料金プラン、機能一覧、FAQ 項目など、指定した形式どおりの型付きペイロードを取得したい場合。JSON Schema をツールに渡すと、それに一致する data と DOM／コンソール／スクリーンショットが返されます。
judge	プリミティブ	美的な仕上がり、ダークパターンのリスク、その他のカスタムルーブリックなど、ルーブリックに基づいて 1 つの URL を評価したい場合。基準ごとのスコア（0..10）と、画面上の位置を示す重大度別の指摘事項が返されます。ビジョン呼び出しは 1 回です。
compare	プリミティブ	同じルーブリックに基づいて 2 つの URL を A/B 比較したい場合。既定の double_blind モードでは、各 URL を個別に評価してから比較を統合します（ビジョン呼び出し 3 回、アンカリングバイアスなし）。fast モードは呼び出し 1 回で、より低コストですが、アンカリングの影響を受けます。
list_personas	メタ	プロジェクトにインストールされているペルソナを確認します。
list_scenarios	メタ	プロジェクトにインストールされているシナリオを確認します。
list_capabilities	メタ	サーバーの機能を自己記述します。提供されるすべてのツールについて、種類／キャッシュ可否／静的コスト帯／副作用／依存関係の宣言に加え、公開環境変数の一覧と現在の結果キャッシュの状態を返します。純粋なイントロスペクションです。初回接続時に一度呼び出して、残りのセッションを計画してください。
calibrate_critic	メタ	ラベル付きフィクスチャを使って批評キャリブレーションのゲートを実行します（合否と一致度の指標を返します）。
get_last_report	メタ	ローカルの履歴 DB から、直近の監査の概要 JSON を読み込みます。

see — 1 回限りのナビゲーションスナップショット

このツールキットで最も軽量なツールです。完全な監査を実行せずに「このページには今何が表示されていますか？」と確認したい場合に呼び出します。

// MCP tools/call arguments
{
  "url": "https://stripe.com/pricing",
  "goal": "Is there a free tier?",      // optional — runs one vision call, ~$0.005
  "wait_for": "networkidle",            // or "load", "domcontentloaded", or a CSS selector
  "viewport_width": 1280,
  "viewport_height": 800,
  "include_dom": true,
  "include_console": true,
  "headless": true,
  "timeout_ms": 30000
}

url_final（リダイレクト後の URL）、title、dom（操作可能な要素数、見出し、概要）、console.errors、screenshot（パスと sha256）、および note（設定されている場合は目標への回答）を含む SeeResult を返します（docs/schemas/see-result.schema.json を参照）。成果物は $AUDIT_SEES_DIR または ~/.pixelcheck/sees/<UTC-iso>-<rand6>/ の下に保存されます。設計の根拠については ADR-011 を参照してください。

act — アクションシーケンスを実行

ブラウザー操作のシーケンス（決定論的操作＋AI）を実行し、各ステップのトレース、最終 DOM、最終スクリーンショットを取得します。エンジンは自動選択されます。決定論的なステップのみのリストは Playwright を直接実行し（コールドスタートは約 1 秒、LLM キーは不要）、少なくとも 1 つのステップが { "type": "act" } の場合にのみ Stagehand が起動します。

// MCP tools/call arguments
{
  "url": "https://stripe.com/pricing",
  "steps": [
    { "type": "fill", "selector": "input[name=email]", "value": "[email protected]" },
    { "type": "click", "selector": "button[type=submit]" },
    { "type": "wait_for", "selector": ".dashboard", "state": "visible" },
    { "type": "screenshot", "label": "after-login" },
    { "type": "act", "instruction": "Click the Upgrade to Pro button" },
    { "type": "note", "goal": "Was the upgrade modal shown? Any error?" }
  ],
  "stop_on_error": true
}

各ステップの種類：

種類	コスト	備考
goto	0	再移動します。wait_for（load / domcontentloaded / networkidle / CSS セレクター）に対応しています。
click / fill / press / wait / wait_for / scroll	0	Playwright を直接実行します。LLM は使用しません。
screenshot	0	呼び出しごとのアーティファクトディレクトリに <label>.png（既定値は step-<index>.png）を書き込みます。
act	約 1 回の LLM 呼び出し	Stagehand が解釈する自然言語のアクションです。セッション全体で Stagehand エンジンが使用されます。
note	約 0.005 ドル	現在のページに対してビジョン呼び出しを 1 回行います。どちらのエンジンでも動作します。

ActResult を返します（docs/schemas/act-result.schema.json を参照）。engine（"playwright" | "stagehand"）、steps[]（各要素に status、duration_ms、cost_usd、および省略可能な screenshot / note / output / error）、最終的な dom / console / screenshot、合計 cost_usd が含まれます。失敗時の動作：stop_on_error: true（既定値）では、最初の失敗後に残りのステップをスキップします（status: "skipped" として記録）。false ではすべてのステップを実行し、1 つでも失敗するとトップレベルの status は "error" になります。アーティファクトは $AUDIT_ACTS_DIR または ~/.pixelcheck/acts/<UTC-iso>-<rand6>/ に保存されます。設計の根拠については ADR-012 を参照してください。

extract — スキーマに基づく構造化抽出

取得したいペイロードを記述する JSON Schema をツールに渡すと、その形状に一致する data が返されます。呼び出しごとに LLM 呼び出しを 1 回行います。常に Stagehand を使用します（extract は本質的に LLM 主導であり、「任意の形状のオブジェクトを返す」ための決定論的な代替手段はありません）。

// MCP tools/call arguments
{
  "url": "https://stripe.com/pricing",
  "schema": {
    "type": "object",
    "properties": {
      "plans": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name":     { "type": "string" },
            "price":    { "type": "number", "description": "Monthly price in USD" },
            "features": { "type": "array",  "items": { "type": "string" } }
          },
          "required": ["name", "price"]
        }
      }
    },
    "required": ["plans"]
  },
  "instruction": "Extract every pricing plan card",   // optional — auto-synthesised from schema field names if omitted
  "selector": "main"                                   // optional — constrain to a sub-region
}

受け付ける JSON Schema のサブセット（それ以外は、キーワードと JSON パスを示す正確なエラーメッセージとともにコンバーターが拒否します）：

受け付けるもの	拒否されるもの
type: object | array | string | number | integer | boolean | null	oneOf、anyOf、allOf、not
type: ["string", "null"]（null 許容の簡略表記）	$ref、patternProperties、dependencies
properties、required、items、enum、description、nullable	if / then / else、const（代わりに要素が 1 つの enum を使用してください）
additionalProperties（受け付けますが無視されます。z.object は既定で余分なプロパティを削除します）
pattern、minLength、maxLength、minimum、maximum（受け付けますが適用されません。LLM はこれらを順守しません）

Stagehand の extract() はオブジェクトスキーマを必要とするため、ルートは type: "object" でなければなりません。type のない { properties: {…} }（オブジェクトの簡略表記）は、オブジェクトとして受け付けられます。

ExtractResult を返します（docs/schemas/extract-result.schema.json を参照）。engine: "stagehand"、data（指定したスキーマに一致）、schema_used / instruction_used / selector_used（クライアント側での再検証とデバッグ用にそのまま返されます）、dom / console / screenshot、および Stagehand の metrics.extractPromptTokens × estimateCost(model, …) から算出された cost_usd が含まれます。再生用に、data.json アーティファクトもスクリーンショットとともに保存されます。recordUsage 中に厳格なコスト上限に達した場合、status は "error" に変わりますが、data と cost_usd は引き続き返されます（一部成功）。アーティファクトは $AUDIT_EXTRACTS_DIR または ~/.pixelcheck/extracts/<UTC-iso>-<rand6>/ に保存されます。設計の根拠については ADR-013 を参照してください。

judge — ルーブリックに基づくページ評価

ルーブリックに照らして、1 つの URL を評価します。美的な仕上がり、ダークパターンのリスク、または指定した任意の評価基準を使用できます。呼び出しごとにビジョン呼び出しを 1 回行います。組み込みのルーブリックは src/core/critics/ にデータとして定義されています。基準 ID は公開仕様の一部であり、利用側は実行をまたいで判定結果をルーブリックに対応付けられます。

// MCP tools/call arguments
{
  "url": "https://stripe.com/pricing",
  "rubrics": ["aesthetic", "dark_pattern"],          // 8 + 12 built-in criteria
  "custom_criteria": [                                // optional one-off rubric
    { "id": "pricing_clarity", "label": "Pricing clarity", "description": "Is total cost visible without scrolling?" }
  ],
  "persona": "us-power-user-desktop",                  // optional — drives viewport/locale via personas/
  "wait_for": "networkidle"
}

組み込みのルーブリック：

ルーブリック	基準	例
aesthetic (8)	visual_hierarchy, typography, alignment_grid, color_contrast, spacing_rhythm, polish, information_density, brand_cohesion	Stripe／Linear／Vercel／Notion を基準に評価
dark_pattern (12)	forced_continuity, hidden_costs, preselected_options, fake_urgency, confirmshaming, obstruction, misdirection, trick_questions, disguised_ads, bait_and_switch, privacy_zuckering, nagging	Brignull の分類法＋ノルウェー消費者評議会 2018 年
custom	呼び出し側が指定	価格の明確さ、コンバージョン経路、アクセシビリティに関する説明など、任意の単発ルーブリック

評価の方向は種類にかかわらず一貫しており、スコアが高いほど良好です。美的評価の 10 は優れていることを示し、ダークパターン評価の 10 はダークパターンが検出されなかったことを示します。そのため、overall_score（すべての判定スコアの平均）は、異なるルーブリックを組み合わせても単調に変化します。

rubrics、プロンプトに展開されたルーブリック全体を含む criteria、基準ごとの { criterion_id, score, rationale, evidence } を含む verdicts[]、location を含む重大度別の問題を示す findings[]、overall_score、summary、および標準の dom／console／screenshot／cost_usd エンベロープを含む JudgeResult を返します（docs/schemas/judge-result.schema.json を参照）。成果物は $AUDIT_JUDGES_DIR または ~/.pixelcheck/judges/<UTC-iso>-<rand6>/judge.json に保存されます。設計の根拠については ADR-014 を参照してください。

compare — A/B ページ比較

共通のルーブリックを使って、2 つのページを A/B 比較します。デフォルトのモードは double_blind です。両方のページを同じルーブリックで個別に（並列で）評価した後、両方のスクリーンショットを並べて表示し、先行する判定結果をコンテキストとして参照するビジョン合成呼び出しを 1 回実行します。ビジョン呼び出しは合計 3 回ですが、評価は並列で実行されるため、実際の所要時間は約 2 回分です。この方式は、各候補を個別に評価してから比較結果をまとめるという、Nielsen Norman や Baymard Institute などの商用 UX レビューの慣行に倣っています。その理由はアンカリングバイアスです。1 つのプロンプトで 2 つのページをスコア付けするようモデルに依頼すると、絶対スコアがページ自体ではなく、ページ間の差に引き寄せられます。

fast モードでは、横並びのビジョン呼び出し 1 回にまとめます。より安価（約 3 倍）ですが、アンカリングの影響を受けます。呼び出しごとの精度よりコスト比率が重要なバッチ比較（例：競合他社 100 社のページを一晩で評価する場合）では、このモードを選択してください。

// MCP tools/call arguments
{
  "a": { "url": "https://stripe.com/pricing" },
  "b": { "url": "https://intercom.com/pricing", "viewport_width": 375, "viewport_height": 812 },
  "rubrics": ["aesthetic", "dark_pattern"],
  "mode": "double_blind"                                // default; use "fast" for cheap batches
}

各側の viewport を指定すると、たとえばデスクトップの A とモバイルの B を比較できます。どちらの側にも、以前の see／extract／judge 呼び出しで取得したスナップショット（{ "capture": { ... } }）を指定できます。この場合、ツールはその側ではブラウザーを起動しません。

mode、rubrics、criteria、side_a／side_b（それぞれに double_blind モード時の埋め込み JudgeResult、各側のスクリーンショット、成果物ディレクトリを含む）、per_criterion[]（{ criterion_id, score_a, score_b, winner: "a"|"b"|"tie", rationale }）、overall_winner、summary、合計の cost_usd を含む CompareResult を返します（docs/schemas/compare-result.schema.json を参照）。成果物は $AUDIT_COMPARES_DIR または ~/.pixelcheck/compares/<UTC-iso>-<rand6>/ に保存されます。ここには a/ と b/ のサブディレクトリ、および compare.json のサイドカーファイルが含まれます。

list_capabilities — 自己記述

初回接続時に一度呼び出すと、サーバー全体の構造化マップを取得できます。すべてのツールについて、種別、入力スキーマ、結果スキーマのタイトル、キャッシュ可能性、静的なコスト見積もりの範囲、副作用、依存関係の宣言を確認できるほか、公開されている環境変数の一覧と結果キャッシュの現在の状態も取得できます。

// MCP tools/call arguments — none required
{}

ListCapabilitiesResult を返します（docs/schemas/list-capabilities-result.schema.json を参照）。

{
  "schema_version": "1.2.0",
  "server": { "name": "pixelcheck", "version": "0.3.0" },
  "result_schema_version": "1.2.0",
  "tools": [
    {
      "name": "judge",
      "kind": "primitive",
      "result_schema": "JudgeResult",
      "cacheable": true,
      "cost_estimate_usd": { "typical": 0.02, "min": 0.01, "max": 0.06, "unit": "per_call", "notes": "..." },
      "side_effects": ["navigation", "network_egress", "fs_writes_artifacts"],
      "requires": { "api_keys": ["ANTHROPIC_API_KEY"], "browser": true }
      /* …plus name / description / input_schema */
    }
    /* …11 more rows */
  ],
  "env": [
    { "name": "ANTHROPIC_API_KEY", "scope": "auth", "default": "", "required": true, "description": "..." }
    /* …20 more rows across auth / cache / cost_guard / artifacts / logging / memory / reports */
  ],
  "cache": { "enabled": true, "ttl_ms_default": 86400000, "path": "~/.pixelcheck/result-cache.db" }
}

純粋なイントロスペクションです。 LLM もブラウザーも使用せず、シークレットの有無も調べません。シークレットの環境変数は、設定すべき変数が分かるように 名前 は返しますが、値は決して返しません。キャッシュファイルのパスは公開されます。パスはシークレットではなく、診断／クリーンアップ用スクリプトを作成するエージェントにとって実際に必要だからです。設計の根拠（tools/list が厳密な仕様に準拠したサブセットを維持する理由や、実行時にシークレットの有無を意図的に調べない理由を含む）については、ADR-016 を参照してください。

すべてのツールのレスポンスには、docs/contracts/RESULT_SCHEMA.md に従って最上位の schema_version フィールドが含まれます。同一サーバープロセス内の2つの並行ツール呼び出しは、それぞれ独立した実行時の米ドル建てコスト上限を持ちます（ADR-009 を参照）。ただし、永続的な日次台帳は共有します。

新しいツールを追加するには、src/mcp/tools/<name>.ts に ToolDefinition をエクスポートするファイルを配置し、src/mcp/server.ts の ALL_TOOLS に追加します。レジストリの設計根拠については、ADR-010 を参照してください。

複数プロジェクトのサポート

1つの PixelCheck インストールで、すべてのプロジェクトに対応します。

pixelcheck/
 |-- personas/              # 18 shared personas (used by all projects)
 |-- projects/
      |-- my-saas/          # Project A
      |    |-- config.yaml
      |    |-- scenarios/
      |-- my-mobile-web/    # Project B
      |    |-- config.yaml
      |    |-- scenarios/
      |    |-- personas/    # Optional: project-specific persona overrides
      |-- my-docs-site/     # Project C
           |-- config.yaml
           |-- scenarios/

安全性

• Stripe のライブキー保護 — 環境変数内に pk_live_ が検出された場合、起動を拒否します
• 認証情報の秘匿化 — OAuth トークン、パスワード、API キー、Webhook URL は、レポートにもログにも書き込まれません（2層構造です。apiKey／password／token／cookie などの一般的なフィールド名は常に秘匿化され、環境変数から取得した具体的なシークレット値は、ログメッセージ内を含め、出現箇所をすべて部分文字列単位で置き換えます）
• Computer Use のガードレール — Anthropic のプロンプトインジェクション分類器がデフォルトで有効です
• 予算上限 — 累積 API コストがしきい値を超えると、新しい監査単位の起動を停止します

ロギング

内部イベントには構造化ロガー（pino）を使用します。出力先は stderr なので、CLI の結果と MCP の stdio プロトコル向けに stdout はクリーンな状態に保たれます。デフォルトでは、stderr が TTY の場合は人間が読みやすい形式、それ以外の場合は JSON 形式で出力します。

環境変数	値	デフォルト	効果
LOG_LEVEL	trace、debug、info、warn、error、fatal、silent	info	最小ログレベル
LOG_PRETTY	1、true、0、false、auto	auto	整形表示または JSON 形式を強制します。auto の場合は TTY かどうかで決まります
LOG_FILE	/path/to.log	未設定	ログをファイルにも同時出力します

例：

# CI / piped: JSON to stderr automatically (no TTY)
pixelcheck run --project projects/my-app 2> audit.log

# Force JSON even in a terminal
LOG_PRETTY=0 pixelcheck run --project projects/my-app

# Verbose debugging
LOG_LEVEL=debug pixelcheck run --project projects/my-app

コストガード

プロセス全体に適用される支出上限により、LLM の請求額が予期せず膨らむのを防ぎます。Anthropic API のすべての呼び出しは、次の 2 つの上限に対して追跡されます。

• 実行ごと — 1 回の監査／MCP ツール呼び出しです。実行開始時にリセットされます。
• 日ごと — UTC 日単位の合計です。JSON 台帳にプロセスをまたいで保存されます（デフォルトは ~/.pixelcheck/cost-ledger.json。AUDIT_COST_LEDGER_PATH で変更できます）。

いずれかの上限を超えると BudgetExceededError がスローされ、呼び出し元のループは直ちに停止します。台帳の 30 日を超えるエントリーは自動的に削除されます。

環境変数	デフォルト	効果
AUDIT_COST_MAX_RUN_USD	5	監査実行／MCP ツール呼び出しあたりの最大 USD 額
AUDIT_COST_MAX_RUN_TOKENS	10000000	実行あたりの入力＋出力トークンの最大数
AUDIT_COST_MAX_DAILY_USD	50	すべての実行を合算した、UTC 日あたりの最大 USD 額
AUDIT_COST_MAX_DAILY_TOKENS	100000000	UTC 日あたりの入力＋出力トークンの最大数
AUDIT_COST_LEDGER_PATH	~/.pixelcheck/cost-ledger.json	日次台帳の永続化先パス
AUDIT_COST_GUARD_DISABLED	未設定	1／true を指定すると完全に無効化します（CI／テスト用）

コストガードは、ランナーの budget_usd 上限に加えて適用されます（この上限とは独立しています）。budget_usd はランナーによる新しいユニットのスケジュールのみを停止します。コストガードは、直接の MCP ツール呼び出し、コンピューター操作ループ、ユニットスケジューラーが認識しない指示の変更を検出します。

run started のログ行に含まれるスナップショット、または次の方法で現在の状態を確認できます。

LOG_LEVEL=debug pixelcheck run --project projects/my-app
# emits one "llm usage recorded" debug line per Anthropic call with running totals

並行実行の安全性

PixelCheck は、複数のプロセスから同時に実行しても安全です。たとえば、2 つの pixelcheck ターミナルを並行して実行する場合、MCP サーバーが 2 つの audit_url 呼び出しを並行して処理する場合、CLI の実行と MCP が提供する呼び出しを同時に行う場合などが該当します。具体的には次のとおりです。

• コスト台帳（cost-ledger.json）：プロセス間で共有されるアドバイザリロックファイル（<ledger>.lock）で保護されます。並行して記録しても更新が失われることはありません。
• 実行ごとのコストカウンター：各 MCP ツールのディスパッチと各 runAudit 呼び出しは、それぞれ独自の AsyncLocalStorage スコープを取得します。そのため、並行する 2 つの呼び出しは、それぞれ独立した実行あたりの USD 上限を持ちます。永続化される日次台帳は引き続き共有されます。
• メモリ DB（memory.db）：record(fact) は、単一のアトミックな INSERT … ON CONFLICT DO UPDATE を使用します。SELECT の後に書き込む際の競合は発生しません。
• ビジュアル差分のベースライン：初回実行時の初期化では、.tmp パスにコピーした後、linkSync で配置します。初回実行が 2 つ並行しても両方とも成功し、先に書き込んだ側が採用されます。

コスト台帳のロックを保持中にプロセスがクラッシュした場合、ロックは 30 秒後に自動復旧します（または、ロック保持プロセスの pid がすでに稼働していなければ、それより早く復旧します）。設計については ADR-009 を参照してください。

SQLite ストアは統一されたマイグレーションランナーを共有します

PixelCheck は、4 つのローカル SQLite ファイル（history.db／memory.db／plan-cache.db／result-cache.db）を使用します。これらはすべて src/core/db-migrate.ts > openManagedDatabase() を通じて開かれます。この関数は、親ディレクトリの作成、busy_timeout プラグマ、ファイルロックを使用した WAL への切り替え、PRAGMA user_version に基づくマイグレーションの適用を一元的に処理します。各マイグレーションは独自の BEGIN IMMEDIATE／COMMIT ブロック内で実行されるため、SQL エラーが発生すると、そのステップ内のすべての CREATE／ALTER／INSERT がアトミックにロールバックされ、スキーマが部分的に適用されることはありません。新しい DB を開く古いバイナリは、存在しない列に対して壊れたクエリを実行するのではなく、MigrationVersionError を明示的に発生させます。設計については ADR-026 を参照してください。

結果キャッシュ

永続的なローカルキャッシュは、決定論的なプリミティブの結果をメモ化するため、同一の呼び出しを繰り返すと cost_usd = 0 ですぐに返されます。AI エージェントは、ツールを呼び出すたびに新たなビジョントークンを消費することなく、より積極的に計画できます。

キャッシュ対象のプリミティブ：

プリミティブ	キャッシュ	備考
judge	✅	同じ URL + ルーブリック + カスタム基準 + ペルソナ／モデルの場合、同じ判定が返されます。
extract	✅	同じ URL + スキーマ + 指示 + セレクター + ペルソナ／モデルの場合、同じ data が返されます。
see	✅ goal が設定されている場合	goal がなければ LLM コストは発生しません。スナップショットをキャッシュすると、古い情報を返すおそれがあります。
act	❌	状態を変更するセマンティクスのため、常に新たに実行されます。
compare	透過的	2 つのサイドごとの judge 呼び出しは自動的にキャッシュを利用します。統合呼び出しは個別にはキャッシュされません。

ヒット／ミスのセマンティクス： キャッシュ対応の各結果には、オプションの cache?: { hit, age_ms, key, cost_saved_usd? } フィールドが含まれます。ヒット時には、結果自身の cost_usd がゼロに設定され、元のコストは cache.cost_saved_usd に移されます。そのため、呼び出し元がネストされたコスト（例：compare）を合計しても、キャッシュされた処理が二重に計上されません。

設定：

環境変数	デフォルト	効果
AUDIT_RESULT_CACHE_PATH	~/.pixelcheck/result-cache.db	SQLite のパス。環境ごとに分離します
AUDIT_RESULT_CACHE_TTL_MS	86400000（24時間）	これより古いエントリーはミスとして扱われ、削除されます
AUDIT_RESULT_CACHE_DISABLED	未設定	1／true を指定すると完全にバイパスします（読み取り＝ミス、書き込み＝何もしない）
AUDIT_RESULT_CACHE_MAX_ROWS	10000	LRU 上限。この値を超えると、last_used_at が最も古い行から削除されます。0 で無効になります。
AUDIT_RESULT_CACHE_MAX_DISK_MB	500	DB サイズによる LRU 上限。同じ順序で削除されます。0 で無効になります。

呼び出しごとのオーバーライド（各 MCP ツールで cache／cache_bust／cache_ttl_ms としても公開されています）：

• cache: false — この呼び出しでは読み取りと書き込みをスキップします。
• cacheBust: true — 読み取りをスキップしますが、新しい結果を保存するため、以降の同一呼び出しではキャッシュがヒットします。
• cacheTtlMs: number — この呼び出しの TTL をオーバーライドします。

スキーマバージョンによる無効化： 異なる RESULT_SCHEMA_VERSION のもとで書き込まれたエントリーはミスとして扱われ、次回のプルーニング時に削除されます。加算的なマイナーバージョンの更新ではキャッシュは自動的に維持されます。メジャーバージョンの更新ではすべて無効になります。

設計については、ADR-015 を参照してください。

成果物の保持

各 MCP プリミティブ呼び出し（see／act／extract／judge／compare）は、スクリーンショット、DOM ダンプ、ペイロード JSON、LLM の応答を含む、呼び出しごとのサブディレクトリを ~/.pixelcheck/<kind>/ の下に作成します。長時間稼働する MCP サーバーでは、1 か月で数ギガバイトに達することがあります。PixelCheck はデフォルトで 30 日間の保持期間を適用し、遅延プルーニングを行います。

pixelcheck prune          # explicit cleanup; prints summary, exit 1 on errors

MCP サーバーは起動時に同じプルーニングを最大 24 時間に 1 回実行します （prune-stamp.json に前回の実行時刻が記録されます。期間内に再接続した場合は、 プルーニング全体がスキップされます）。

環境変数	デフォルト	効果
AUDIT_SEES_RETENTION_DAYS	30	see 成果物の保持期間。0 で無効になります
AUDIT_ACTS_RETENTION_DAYS	30	同上。act が対象です
AUDIT_EXTRACTS_RETENTION_DAYS	30	同上。extract が対象です
AUDIT_JUDGES_RETENTION_DAYS	30	同上。judge が対象です
AUDIT_COMPARES_RETENTION_DAYS	30	同上。compare が対象です
AUDIT_<KIND>_DIR	~/.pixelcheck/<kind>	種類ごとのカスタム保存ディレクトリ

保持期間に 0 を設定すると無期限保持を意味し（その種類のプルーニングをスキップします）、Linux のすべての保持ツールと同じ動作になります。種類ごとにまとめて削除するには、rm -rf ~/.pixelcheck/<kind> を直接使用してください。

使用技術

• Playwright — ブラウザーの自動化
• Stagehand 3.x — AI によるセマンティックなブラウザー制御
• Claude（Vision + Computer Use）— 視覚的な評価とピクセルレベルのレビュー
• axe-core — WCAG アクセシビリティ監査
• better-sqlite3 — ローカルでの監査履歴と傾向の追跡

何が違うのですか？

現在、AI エージェントにビジュアル Web を操作させる方法は、実質的に4つあります。それぞれ異なるアプローチを採用しています。

• オープンソースの自動化フレームワーク — browser-use（91k★）、Stagehand（22k★）、Skyvern（21k★）。エージェントが指示した タスクの実行 において最高クラスです。いずれも複数ペルソナのシミュレーションレイヤーを備えておらず、キャッシュ可能な AI ワークフロー向けに設計された厳格な結果スキーマの契約もありません。
• ルールベースの監査ツール — axe-core（7k★）、pa11y（4.4k★）、Lighthouse。「WCAG に準拠しているか？」を確認するには優れていますが、「このプロダクトは本当に優れているか？」には答えません。
• ホスト型エージェントブラウザー — Comet、Atlas、BrowserOS、Dia。Chrome を置き換えるコンシューマー向け製品です。クレジットカードとセッションを渡せば、UI は提供されますが、インフラは提供されません。
• PixelCheck — AI エージェントのワークフローを支える MCP サーバーです。完全にローカルで、完全なオープンソースで、完全に自分の管理下に置けます。

	オープンソースフレームワーク	ルールベースの監査ツール	ホスト型エージェントブラウザー	PixelCheck
答える質問	ブラウザーをどう制御するか？	WCAG 2.x に準拠しているか？	プロダクトに Web を調べてもらえるか？	自分の AI エージェント は Web をどう認識し、操作するか？
主なインターフェース	ライブラリ / SDK	CLI	デスクトップアプリ + クラウドセッション	MCP サーバー（+ 人間向け CLI）
インテリジェンス	LLM 主導のアクション	静的ルール	ホスト型 LLM（セッションごとに課金）	LLM によるビジョン + ルール + Computer Use、自分の LLM キー
ユーザーシミュレーション	匿名の単一セッション	なし	サインイン済みの単一セッション	18 のペルソナ × 17 か国 × 6 種類のスクリプトシステム
検出回避	なし	該当なし	組み込み（ブラウザー識別情報）	9 種類のフィンガープリント + 15 種類のステルスパッチ
出力契約	アクションの結果	合否チェックリスト	会話形式の応答	公開済み JSON Schema 31 種 + 名前付き API 89 種
履歴	なし	なし	セッション単位、ベンダーにロックイン	SQLite による傾向分析 + 実行間の差分、自分のもの
料金モデル	無料のオープンソース、自分の LLM 利用料	無料のオープンソース	サブスクリプション + セッションごとの料金	無料のオープンソース、自分の LLM 利用料、PixelCheck の上乗せ料金なし
データの保存場所	自分のマシン	自分のマシン	ベンダーのクラウド	自分のマシン。以上です。
ロックイン	場合によってあり（クラウドの追加機能）	なし	最大	なし — MIT、課金プランなし、商用フォークなし

MCP を第一とするブラウザープリミティブ、複数ペルソナのシミュレーション、AI ビジョンスコアリング、WCAG 分析、ステルスフィンガープリント、履歴による傾向追跡を組み合わせた既存のオープンソースプロジェクトはありません。PixelCheck は、AI エージェントとビジュアル Web の間に欠けていたインフラレイヤーです。そして、上の表にある中で「データはどうなるのか？」という問いに「自分のマシンから外に出ることはありません」と答えられる唯一のものです。

テストカバレッジ

計測付きで実行します。

npm run test:coverage          # writes ./coverage/index.html
npm run test:coverage:check    # CI gate — fails on regression below thresholds

カバレッジは vitest.config.ts > coverage.thresholds（プロバイダー v8）で強制されます。エントリーポイント（cli.ts、index.ts、mcp/server.ts）と純粋な型の契約（core/types.ts、core/result-schema.ts）は除外されています。これらは利用側を通じてテストされます（CLI のスモークテスト + MCP の tools/list ハンドシェイク + スキーマのラウンドトリップテスト）。これらを数に含めると、シグナルが薄まります。

閾値の下限は現在の全体的なベースライン以下に設定されているため、ゲートはリグレッションを検出しつつ、ビルドを妨げません。新しいテストを含む PR を追加するたびに、下限を引き上げます。モジュールごとのカバレッジは、テキスト形式の表レポートまたは coverage/index.html で確認できます。フェーズ計画については、docs/decisions/ADR-017-coverage-tooling-and-m1-2-phase-1.md を参照してください。

パフォーマンス回帰ゲート

ホットパスのベンチマークは tests/perf.bench.ts にあり、テストスイートとは別に実行されます（vitest の *.bench.ts の検出は *.test.ts とは独立しているため、npm test は高速なままです）。9 つのベンチマークで、テンプレートのリファクタリングや O(N²) ループの追加によって最も回帰が起きやすい、レポートのレンダリングと集計のパスをカバーしています。

• renderPdfHtml / renderTrendsHtml / renderDiffMarkdown / renderDiffHtml
• renderJunitXml / renderSarif
• summarizeWcag / computeSummary / t() の i18n 参照

npm run bench          # measure (writes docs/perf-current.json)
npm run bench:check    # compare to docs/perf-baseline.json — exit 1 on regression > 50%
npm run bench:update   # bake current as new baseline (after intentional perf changes)

デフォルトの許容値 50% は、実測した実行ごとのばらつき（静かなハードウェアで 8〜53%）を基に調整されています。ローカルでより厳しくチェックするには --tolerance 0.30 を指定してください。初期ベースラインは 連続する 5 回の実行の最小値として記録されており、回帰は「これまでより遅い」と判定されます。下限を超えるノイズに対して堅牢です。設計の詳細は ADR-025 を参照してください。

安定性に関するコミットメント

v1.0.0 から、以下のインターフェースは セマンティックバージョニングに基づいて安定しています。

• CLI — フラグ、サブコマンド、終了コード、環境変数名
• 設定スキーマ — config.yaml / personas/*.yaml / scenarios/*.yaml
• 結果スキーマ — バージョン 1.2.0、docs/schemas/ で公開されている 31 個の JSON スキーマ
• MCP ツールのインターフェース — 13 個のツール名と入出力スキーマ
• ライブラリエクスポート — src/index.ts からの 89 個の名前付きエクスポート

破壊的変更は メジャーバージョンの更新（v2.0、v3.0、...）でのみ導入されます。マイナーリリースとパッチリリースでは、後方互換性が保証されます。非推奨化のサイクルは docs/DEPRECATION-POLICY.md に記載されています。v1.x で非推奨となった機能は、次のメジャーバージョンで削除されるまで、少なくとも 2 回のマイナーリリースにわたって引き続き動作します。

v0.3 から v1.0 へのアップグレードについては、MIGRATION.md を参照してください。

パフォーマンスのベースライン（暫定、v1.0-rc1 のキャリブレーション待ち）

一般的な 5 ユニットの監査（1 シナリオ × 5 ペルソナ、AI パイプライン全体）は、次の範囲に収まる見込みです。

指標	v1.0 の目標	備考
実時間	約 2〜5 分	サイトの複雑さ、ペルソナ数、モデルによって異なります。v1.0-rc1 のキャリブレーションで厳格な SLA を設定します。
API コスト	約 $0.10〜$0.30	Claude Sonnet 4.6 のビジョン機能を使用します。Computer Use の利用が急増すると $0.50 以上になる場合があります。
メモリのピーク	RSS 1 GB 未満	Chromium が約 500 MB、Node ヒープが約 300 MB

レンダリングのホットパス（回帰ゲート npm run bench:check で追跡済み）：

パス	M シリーズでの ops/sec	備考
renderPdfHtml（20 ユニットの監査）	約 12,000	A4 縦向き + WCAG セクション + 5 つのチャート
renderTrendsHtml（100 行の履歴）	約 1,000	インライン SVG チャート 5 つ
renderDiffMarkdown（一般的な PR）	約 90,000	固定表示の PR コメントに適しています
renderSarif（20 ユニット、12 件の問題）	約 190,000	WCAG SC ごとの ruleId

これらはマイクロベンチマーク（単一の関数呼び出し）です。監査パイプライン全体（Chromium の起動 → ページ移動 → スコアリング）の実時間ベースラインは、v1.0-rc1 でキャリブレーション中です。

コントリビューション

コントリビューションを歓迎します。開発者向けガイド（開発環境のセットアップ、コミット規約、PR プロセス、ADR の運用、ブランチ保護）については、CONTRIBUTING.md を参照してください。

コミュニティの行動規範として、Contributor Covenant 2.1 を採用しています。

特に以下の分野でのご協力を歓迎します。

• 代表性の低い地域や人口統計グループ向けの新しいペルソナ
• 一般的なアプリのパターン（e コマースのチェックアウト、オンボーディング、ダッシュボード）向けのシナリオテンプレート
• レポート形式の改善
• コスト最適化の戦略

インストールのトラブルシューティング（企業プロキシ、Alpine、エアギャップ環境など）については、docs/INSTALLATION.md を参照してください。

プライバシーとデータの取り扱い

pixelcheck はすべてお使いのマシン上で実行されます。外部ネットワークへの唯一の接続先は、明示的に実行した監査呼び出しのための api.anthropic.com です。テレメトリーは一切ありません。

監査の実行時にマシンから送信されるデータ：

• ページのスクリーンショットと DOM の概要 → Anthropic Claude API
• シナリオのステップテキストとペルソナのプロフィール項目 → Claude API
• その他のデータは送信されません（URL／環境変数／パス／過去の監査結果はローカルに保存されます）

プライバシーを最優先したデフォルト設定：

• パスワード／シークレット／API キーの入力値は、スクリーンショット撮影前に ******** に置き換えられます（--redact-inputs がデフォルトで有効です。--no-redact-inputs で無効にできますが、フィクスチャ監査の場合に限ります）
• 初回実行時の同意プロンプトで、Anthropic に送信されるデータを明示的にお知らせします。同意内容は ~/.pixelcheck/consent.json に保存されるため、以降の実行では再確認されません。CI／非 TTY 環境では、AUDIT_AUTO_CONSENT=1 環境変数または --auto-consent フラグを使って省略できます（最初に PRIVACY.md をお読みください）。
• 実行ごとのレポートはモード 0700（所有者のみアクセス可能）で <projectDir>/reports/ に保存されます

データフローの詳細、GDPR／CCPA に関する方針、データ保持の制御方法、データの削除方法については、PRIVACY.md をご覧ください。

セキュリティ

脆弱性を発見した場合は、GitHub Security Advisories（非公開での報告）をご利用ください。詳しくは SECURITY.md をご覧ください。セキュリティ上の報告を公開課題として投稿しないでください。

ライセンス

MIT ライセンスです。全文は LICENSE をご覧ください。

サードパーティ製依存関係とそのライセンスについては、docs/THIRD_PARTY_LICENSES.md に記載されています。

ヘルプとリファレンス

• FAQ.md — API キーと費用、シナリオとペルソナ、レポートと出力、プライバシー、ネイティブバイナリに関するよくある質問
• docs/TROUBLESHOOTING.md — 実行時エラーと解決方法（API と認証、監査の実行、ブラウザー、レポート、CI、パフォーマンス）
• docs/INSTALLATION.md — インストールの対応状況、企業プロキシ、Alpine／Docker／エアギャップ環境向けの手順
• API リファレンス — npm run docs:api を実行してローカルで生成します → docs/api/index.html（TypeDoc。コミット対象外）
• docs/decisions/ — 設計の根拠を説明する 28 件のアーキテクチャ決定記録

---

E2E テストはコードが動作することを検証します。PixelCheck は AI エージェントに、製品が正しく動作することを検証するための本物の目と手を与えます。
2 分で始める