pagouse

ピクセルではなく参照で。 pagouse はコーディングエージェント向けのページエージェントです。通常プロファイル上で動作する Chromium 拡張機能で、アクセシビリティツリーを読み取り、エージェントに安定した ref_N ラベルを渡し、許可がある場合にのみ、そのノードのクリック、入力、ナビゲーションを行います。

デフォルトでは監視のみ行います。変更操作には --allow-input が必要です。オプションの MCP サーバーは監視専用で、入力操作を実行させることはできません。

$ pagouse --json snapshot --tab 1840 | jq -r '.snapshot.tree' | head
RootWebArea "Inbox" [ref_1]
  textbox "Search" [ref_2]
  button "Compose" [ref_3]

仕組み

• MV3 拡張機能はアクセシビリティツリーをページ内で構築します。これにより、ref は個別の CLI 呼び出しをまたいでも有効なままです。

• ネイティブメッセージングは pagoused を起動します。これはオーナーのみがアクセスできる unix ソケット上で動作するローカルデーモンです。リモートデバッグポートも chrome.debugger も使用しません。

• 依存関係ゼロの Python コアが、バージョン管理された --json エンベロープ（schema: 1）でこれらすべてを包みます。

レイヤーと非目標については、docs/architecture.md を参照してください。

Related MCP server: Playwright MCP

要件

• Linux

• Python 3.13+ と uv

• Chromium 系ブラウザ（Chrome、Chromium、Brave、Edge）の通常プロファイル

コア自体は依存関係ゼロです。magick は --fit によるダウンスケーリングにのみオプションで必要です。

インストール

git clone https://github.com/gianlucamazza/pagouse
cd pagouse
./install.sh

install.sh は pagouse を uv ツールとしてインストールし、~/.config/pagouse/config.toml が存在しない場合は作成し、エージェントスキルを既存のスキルルートにリンクし、ネイティブメッセージングホストを登録します。冪等です。詳細は docs/quickstart.md を参照してください。

次に、extension/ を展開して読み込みます（chrome://extensions → デベロッパーモード）。ポップアップが緑になれば、pagouse --json doctor は ready を報告するはずです。

使い方

監視 — 許可は不要です：

pagouse --json tabs
pagouse --json snapshot --tab ID

操作 — --allow-input を追加し、座標ではなく ref でクリックします：

pagouse --json --allow-input click --ref ref_4 --tab ID --then snapshot

すべてのコマンドとフラグ：docs/cli-reference.md。エンベロープとエラーコード：docs/json-contract.md。

MCP 追加機能とエージェントスキル

uv tool install 'pagouse[mcp]' は pagouse-mcp を提供します：読み取り専用の監視ツールのみです（doctor、tabs、snapshot、shot、wait、wait_ref）。変更ツールはありません。ページの操作は CLI と許可を通じて行ってください。

install.sh は skills/pagouse/SKILL.md を既存のエージェントスキルルートにリンクするため、エージェントはセットアップなしでプレイブックを利用できます。

セキュリティ

監視は許可を要求しません。変更操作は明示的な許可なしには拒否されます。スキーム拒否、オリジンポリシー、シークレットの秘匿化はコアで強制されます。タブのタイトル、URL、ツリーのテキスト、スクリーンショットのピクセルは信頼できない入力です。入力を有効にする前に docs/security-model.md を読んでください。脆弱性は SECURITY.md に従って報告してください。

ドキュメント

ライセンス

MIT。LICENSE を参照してください。