hwatu

hwatu はコーディングエージェント向けのヘッドレス検証ハーネスです。CLI、MCP、または Unix ソケット接続ごとに 1 行の JSON を通じて操作する、常駐型の WebKit デーモンです。「見た目は問題なさそうです」の代わりに、エージェントは 約 35 ミリ秒で 1 回の呼び出しによる検証済みページチェック、改善を重ねられるピクセル差分スコア、数値化されたアニメーション、そして並列数を問わずフォーカスを奪わないヘッドレスウィンドウを利用できます。Jcode は browser バックエンドとしてネイティブに操作します。CAPTCHA や判断を要する場面など、人間による確認が必要な場合は、hwatu focus <id> を実行すると、同じライブセッションが実際のウィンドウとして表示されます。

ドキュメント

• エージェントガイド：プロトコル、プリミティブ、検証ループ
• ベンチマーク：測定方法とともに、すべての数値を掲載
• ビジョン：持続的な製品原則、ネイティブプラットフォーム戦略
• 人間向けガイド：タイル型 WM ブラウザーとしての hwatu、キーバインド、引き継ぎ
• ロードマップ：製品ポートフォリオの優先事項と境界
  • AI 検証
  • タイル型 WM ブラウザー
  • 共有プラットフォーム
• macOS の調査：WKWebView の実測プローブ、競合調査、macOS を検証専用とする理由
• 継続的な改善：アクティベーション指標、フィードバックループ、週間サイクル
• ローンチキット：再利用可能な紹介文、チャネル、測定計画

インストール

curl -fsSL https://raw.githubusercontent.com/hongnoul/hwatu/main/scripts/install.sh | bash

静的バイナリ 1 つと、お使いのディストリビューションの webkitgtk-6.0 が必要です（インストーラーが確認します）。Arch では yay -S hwatu を実行してください。ソースからビルドする場合は、cargo build --release を実行します。

続いて、エージェントを接続します。

hwatu setup             # detect Claude Code, Cursor, Jcode, or MCP

直感ではなく、検証を

• 「ピクセル単位で完全一致」は主張です。match_percent: 97.49は測定値です。
• ページチェックはツール呼び出し1回、約35 msです。ウォーム状態のサーバーでPlaywrightを使って同じ処理をすると、呼び出しは5回になり、約9倍遅くなります。
• デフォルトではヘッドレスです。ウィンドウは表示されず、フォーカスも奪われないので、入力を続けられます。
• 単一の静的バイナリと、お使いのディストリビューションのwebkitgtkだけで動作します。Nodeも、170 MBのChromiumのダウンロードも不要です。

hwatu setupは、設定を変更せずに対応するコーディングエージェントを検出します。 クライアントを明示的に選択してください。

hwatu doctor
hwatu setup --client claude --scope project --dry-run
hwatu setup --client claude --scope project
hwatu demo

セットアップは事前確認が可能（--dry-run）で、冪等性があり、元に戻せます （--undo）。手動でMCPを設定する場合は、移植可能な次のエントリーを1つ追加します。

{ "mcpServers": { "hwatu": { "command": "hwatu", "args": ["mcp"] } } }

またはMCPを使わず、各コマンドを短いCLI呼び出しとして実行するか、Unixソケット経由で改行区切りのJSONを1行送信します。

hwatuに接続するとそのツールを利用できるようになります。プロジェクトの指示を追加すると、エージェントがいつツールを使うかを指定できます。AGENTS.md、CLAUDE.md、またはCursorのルールに次の内容を追加してください。

## Frontend verification

Use Hwatu after frontend changes. Exercise the affected user journey and
verify its intended visible, navigational, or persisted result with `expect`.
A successful click or clean console is not proof of success. Check `console`
for additional JavaScript and request failures after verifying the outcome.

次に、タスクの検証内容を具体化します。

Implement display-name editing on /settings. Use Hwatu to enter “Test User,”
save it, verify the visible success state, reload, confirm persistence, and
report any console errors.

検証のループ：

hwatu --headless localhost:3000        # its window; you never see it
hwatu --headless staging.example.com   # the reference

hwatu diff --id 2 --other 1 --heatmap /tmp/heat.png
# {"match_percent":85.13,"regions":[{"x":0,"y":160,"w":2048,...}]}

hwatu motion --id 1                    # the reference's animations, as numbers
# easing cubic-bezier(0.25,1,0.5,1), 300ms, marquee 29.78px/s ...

# ...agent edits code...

hwatu diff --id 2 --other 1
# {"match_percent":97.49}              # climbing beats guessing

このループにより、stripe.comのランディングページのクローンのピクセル一致率が85.1%から98.8%に向上しました。再現するにはこちらをご覧ください：scripts/demo/。証拠マニフェスト付きの、もう1つの実エージェントのシナリオ（レスポンシブ表示の差分を4つ確認した後、人間にライブで引き継ぐ）はこちらです：scripts/demo-aiuc/。

検証を一通り実行する（開く、読み込む、評価する、スクリーンショットを撮る、閉じる）のに必要なのは、1つのコマンド、1回のツール呼び出し、中央値で約35 msです （ベンチマーク）。

hwatu check localhost:5173 --eval 'document.title' --shot=/tmp/after.png
# {"title":"My App","eval":"My App","shot":"/tmp/after.png",
#  "console":[...],"load_ms":13,"total_ms":35}

プリフライト、ローカル開発サーバー、レスポンシブスクリーンショット、ソースの古さのチェック、証拠レポートも担う、リポジトリレベルで繰り返し使える契約が必要な場合：

hwatu verify .hwatu/about.verify.json

同じ実行機能は、verify_uiとしてMCPクライアントにも公開されているため、エージェントハーネスでオーケストレーションのループを再構築する必要はありません。エージェントガイドをご覧ください。

生成済みのHTMLが手元にあり、サーバーがない場合は、hwatu renderを使うと、マークアップを入力として同じ処理を1回の呼び出しで実行できます。一時ファイルもpython3 -m http.serverも不要です。

echo '<h1>generated</h1>' | hwatu render --stdin --shot=/tmp/gen.png
# {"rendered":true,"shot":"/tmp/gen.png","load_ms":5,"total_ms":28}

# React to load, console, download, and window events without polling.
hwatu watch --kinds load,console
# {"event":"load","seq":1,"window_id":7,"data":{"state":"started",...}}

MCPクライアントはsubscribe_eventsを呼び出して、notifications/hwatu/eventと同じストリームを購読します。プロトコルと検証ループの全容については、エージェントガイドをご覧ください。

ほかの環境では、ヘッドレスかどうかは起動時に決まり、人間がセッションを見ることはできません。hwatuではヘッドレスかどうかはウィンドウのプロパティで、ライブで双方向に切り替えられます。hwatu focus <id>を実行すると、ヘッドレスセッションを状態を保ったまま実ウィンドウに切り替え、人間に引き継げます。

設計上、challengeが行うのは検出と引き継ぎのみです。ソルバーAPI、トークンの注入、フィンガープリントの偽装はありません。

引き継ぎ先

引き継ぎが機能するのは、hwatuがタイル型ウィンドウマネージャー（WM）向けに構築された、本格的なブラウザーでもあるからです。hwatu <url>を実行すると、ターミナルがシェルを開くようにウィンドウが開きます（タブバーはWMが担うため、ウィンドウ内にはありません）。標準的なキーバインド（ctrl+l、ctrl+f、ctrl+kのパレット。再割り当て可能）、ネイティブの広告ブロック（EasyListの約119,000件のルールをWebKitのコンテンツ拡張エンジンにコンパイルし、リクエスト処理経路でJSを使用しません）、Chromiumのカーブに沿ったスクロール、統一されたショートフォーム操作を備えています。すべてのウィンドウは1つのウォーム状態のデーモンを共有し（ウィンドウが1つ増えるごとに約56 MB）、フォーカスが外れるとサスペンドし、クラッシュ後は最後に表示していたURLで復元します。対応していない機能も明示しています。WebKitGTKではWidevineとパスキーを利用できません。WMの設定ファイル（hyprland、sway、niri）、キーバインド、セットアップについては、docs/human.mdをご覧ください。

特徴

• ヘッドレス／バックグラウンド／フォーカス状態をウィンドウごとのプロパティとして設定でき、実行中に切り替え可能
• 人間への引き継ぎ：hwatu focus <id> でライブセッションをタイル型 WM に表示
• ピクセル差分のスコアリング：一致率＋差分領域＋ヒートマップ（diff）
• アニメーションを数値化：継続時間、イージング、速度（motion）
• アニメーションフレームを決定論的に取得：すべてのアニメーションを時刻 t に固定（seek）
• ピクセルではなくトークンでページ状態を JSON として取得（snapshot）
• 構造化エラーを伴う実際の入力イベント（click／type／scroll／upload）
• JS エラー、コンソール出力、失敗したリクエスト（console）
• JSON Lines または MCP 通知によるプッシュイベントのサブスクリプション（watch）
• ポーリングによる 1 回の呼び出しでのページアサーション（expect）
• 構造化された待機／再開に対応した CAPTCHA／ボット対策検出（challenge）
• MCP サーバー、通常の CLI、1 行の JSON ソケットプロトコル
• 引き継ぎ先となる実ブラウザー：キーバインド、メディア、広告ブロック、クラッシュ後の復元

Playwright や chrome-devtools-mcp ではなく、なぜこれを使うのですか？

エージェントにブラウザーを提供する方法は 3 つあります。

	実行方法	エージェントのループにかかるコスト
コールドライブラリ（タスクごとに起動する Playwright）	スクリプトの実行時にエンジンを起動	呼び出しは速くても、実行は遅い：チェックのたびにエンジンの起動が必要で、タスク間で状態は維持されません
ウォームブラウザー（お使いの Chrome＋devtools-mcp）	人間向けのフルブラウザーを常駐させる	タブ、拡張機能、同期、描画しない UI にリソースを消費し、作業中にウィンドウがフォーカスを奪います
hwatu	「最もコールドなウォームデーモン」：エンジンは起動済みで、それ以外は何もありません	起動は 8 ms、検証済みチェックは 35 ms、表示するよう頼むまで見えません（focus）。どちらの方向からも割り込み可能です

hwatu は、チェックを即座に行うために必要なもの（エンジン、GPU コンテキスト、 コンパイル済みアドブロッカー、事前ウォームアップ済み WebView）だけを維持し、 人間向けのものは、その人がウィンドウを求めた場合を除き、何も維持しません。 そのためタブバーがなくてもウォーム状態でアイドルでき、同じ方法で動かす ウォーム状態を保った Playwright サーバーはクライアントあたり 341 ms かかる一方、 hwatu は 39 ms で済みます（ベンチマーク）。

2 つ目の違いは、返されるものです。Playwright と chrome-devtools-mcp は自動化 API です。エージェントがブラウザーを操作し、 その後、目視確認用の未加工のスクリーンショットや DOM を返します。hwatu は 検証用のブラウザーです。測定プリミティブ（check、 diff、motion、expect）が組み込まれており、ウィンドウの作成にかかる時間は 13 ms、 ヘッドレスは起動モードではなくウィンドウのプロパティです。

hwatu の比較

凡例： ✅ 対応／標準搭載 · 🟡 一部対応／制限あり · ❌ 非対応

機能	Playwright	chrome-devtools-mcp	hwatu
検証パス（読み込み＋評価＋スクリーンショット）、プロセス内でウォーム状態	82 ms	n/a	35 ms
ウォーム状態のサービスとしての検証パス（チェックごとに新しいクライアントを使用）	341 ms	n/a	39 ms
検証パスあたりのツール呼び出し数	5	5	1
ピクセル差分スコア＋領域＋ヒートマップ	🟡 1	❌	✅
数値化されたアニメーション、実行途中の状態を固定	❌ 2	🟡 3	✅
実行中のセッションでヘッドレス ↔ ヘッドありを切り替え	❌	❌	✅
セッション途中で人間に引き継ぎ、状態を維持	❌	❌	✅
エージェントが N 並列で動作してもフォーカスを奪わない	🟡 4	🟡 4	✅
CAPTCHA の検出＋構造化された待機／再開	❌	❌	✅
Node 不要、バージョンごとのブラウザーのダウンロード不要	❌	❌	✅

1 toHaveScreenshot は保存済みのゴールデン画像と比較します。テストスイート向けの合否判定であり、エージェントが改善を目指せるスコアではありません。

2 一般的には、テストの不安定化を避けるため、アニメーションを無効にするか、最終状態まで進めます。

3 生の CDP ではアニメーションの状態を取得できますが、イージング／速度／キーフレームの数値による要約はありません。

4 ヘッドレスでは問題ありませんが、ヘッドありの場合、ウィンドウが毎回ポップアップし、フォーカスを奪います。

この比較は、執筆時点での各プロジェクトの状況を反映しています。 誤りがあればご指摘ください。正直な補足：Playwright はコールドスタート（190 対 435 ms、起動ごとに一度だけ発生）とメモリ使用量で引き続き優れています。hwatu は Chromium ではなく WebKit をレンダリングします（エンジン固有のバグに備え、CI では Playwright のマトリックスを維持してください）。また、現時点では Linux 専用です。詳細な直接比較データと方法については、 docs/benchmarks.mdをご覧ください。

Claude in Chrome との違いは？ カテゴリーが異なります。Claude in Chrome は、拡張機能を通じてあなたの Chrome を操作する単一のエージェント製品です。あなたのプロファイル、タブ、フォーカスを共有し、ほかのものから呼び出すことはできません。hwatu は、CLI/MCP 経由であらゆるエージェントが呼び出せる、クライアントに依存しないデーモンです。専用のウォーム状態の WebKit エンジンを備え、デフォルトでヘッドレスに動作し、検証機能が組み込まれています。Claude と一緒にブラウジングするには Claude in Chrome を、エージェントによる低コストで繰り返し実行でき、測定可能なページチェックには hwatu をお使いください。

フィードバック

チェックの成功、インストールの失敗、キー割り当ての不足、サイトの不具合は、どれも有用な情報です。2 分で記入できる 利用レポートを共有するか、バグを報告してください。

---

MIT ライセンス。Linux。WebKitGTK 6。