shotbox

shotbox

実際のグラフィカルプログラムに、AI エージェントやスクリプト、CI が目と耳と手を持てるようにします。

ウィンドウのあるプログラムを操作するエージェントは、その画面を見たり音を聞いたりできません。shotbox はプログラムを専用の隔離された X11 または Wayland セッションで実行し、それを操作するものが、アクセシビリティツリーの読み取り、スクリーンショットの撮影、再生音の録音、ボタン名によるクリック、文字入力、キーやゲームパッドボタンの長押し、プログラムが実際に準備できるまでの待機を行えるようにします。そのうえで、見つけた内容を計測できます。スクリーンリーダーが読み上げられない名前、コントラスト、Tab の順序、参照画像と比べた変更ピクセル、ちらつく位置、ポインターへの追従速度、音が途切れる位置、使用したリソースなどを調べられます。 実行したものが、誤ってデスクトップやスピーカーに影響することはありません。また、--net loopback を指定すれば、ネットワークにも影響しません。

shotbox で作成：各シーンは隔離されたセッション内で実行される play スクリプトで、shotbox record によって録画されます。音声付き。

claude mcp add shotbox -- shotbox mcp --allow ~/src/app/shotbox-programs

エージェントを使わない場合も、コマンドラインから同じセッションを実行できます。

shotbox shoot editor.png --window 'Text Editor' -- gnome-text-editor notes.md

変更の確認からゲームのスモークテストまで、実際の使用例はこちらです：docs/recipes.md。GUI を操作する他のツールとの違いはこちらです：docs/comparison.md。

エージェント向け

shotbox mcp --allow PROGRAMS を実行すると、エージェントは Model Context Protocol（stdio）経由で隔離されたセッションを利用できます。エージェントはセッションを開始し、PROGRAMS に記載されたプログラム（1 行に NAME = COMMAND を記述し、それ以外は記載しません）を起動して、次の操作を行えます。

• アクセシビリティツリーの読み取りと、画像として返されるスクリーンショットの撮影；
• ノード名によるクリック、キーの押下、文字入力、ゲームパッドの操作；
• ウィンドウ、画面の静止、アナウンスを待機；
• lint、コントラストの計測、Tab 順序の確認；
• セッションで再生される音の録音と、音が途切れた箇所の確認。

これだけで、エージェントは GUI 上で自身の変更を確認したり、ゲームをプレイしてテストしたり、スクリーンリーダーが読み上げる内容を監査したり、毎回同じ条件のセッションでバグ報告を再現したりできます。アクセシビリティツリーは手軽な確認方法で、テキストは 1,000〜2,000 トークンほどです。ピクセルにしか表れないものを確認するには、スクリーンショットを使います。エージェントはリストにないものを実行できず、サーバーが停止するとセッションも終了します。

用途、ツール、構築方法について：docs/mcp.md。

エージェントがシェルから自分でプログラムを実行すると、そのプログラムはデスクトップ上で動作します。画面にウィンドウが開き、スピーカーから音が再生されます。また、xvfb-run の下で実行したブラウザーも、同じように Wayland ディスプレイを見つけます。セッション内で実行するには、プロジェクトの CLAUDE.md または AGENTS.md、あるいは独自のファイルに、次の内容を記載します。

## Graphical programs, browsers and sound

Never run a graphical program, a browser (headless too) or anything that
makes sound straight on this machine: it reaches my desktop and speakers.
Run it in a shotbox session:

- a picture: `shotbox shoot OUT.png --window RE -- COMMAND`
- a script or a test suite with windows: `shotbox run [--audio] -- COMMAND`
- with none, a headless browser say: `shotbox exec [--audio] -- COMMAND`;
  the shotbox package's `sealed()` seals a browser's environment, but
  not the speakers
- a session to come back to: `shotbox start --name NAME`, then
  `shotbox spawn --session NAME -- COMMAND`, and `shotbox stop NAME`

Not `xvfb-run`: it lets `WAYLAND_DISPLAY` and the session bus through. A
server started for a test listens on 127.0.0.1, not 0.0.0.0.

理由

変更内容を確認するエージェントも、README 用のスクリーンショットも、CI のテストも、必要とするものは同じですが、どのプロジェクトも独自のコピーを増やしていました。

• 隔離されています。 意図せず情報が外に漏れることも、プログラムの動作がデスクトップやスピーカーに届くこともありません。bubblewrap がサンドボックスを作成できます（できない場合はその旨を表示します）：隔離される内容。
• スリープではなく、準備完了を待ちます。 ウィンドウが表示される、ポートが開く、ファイルが書き込まれる、ターミナル画面にテキストが表示される、画像が静止するなど、待つ対象を指定できます。sleep 6 を実行して運任せにすることはありません。
• 決定論的です。 Xvfb 上の X11、GTK のソフトウェアレンダラー、LANG=C.UTF-8、TZ=UTC、点滅しないテキストカーソル（GTK、Qt 6.5、ブラウザーのもの。さらに GTK のアニメーションもオフ）、GTK 4 のテキストは本来の色で描画されます。手動でフォントを描画する場合と同様で、GTK のリリースによって自動描画でどれほど薄くなるかには左右されません（詳細）。PNG にタイムスタンプは含まれません。毎回同じ結果になりますが、デスクトップと同じという意味ではありません：デスクトップとの違い。
• 後片付けされます。 各プログラムは独自のプロセスグループで実行され、終了時にはグループ全体が強制終了されます。ラッパースクリプトだけにシグナルを送っても、子プロセスが実行されたままになることはありません。

インストール

Debian では、各コマンドとオプションが利用できるものとともに、次のようにします。

sudo apt install xvfb xauth dbus-daemon imagemagick x11-utils python3-gi gir1.2-vte-2.91 \
  at-spi2-core gir1.2-atspi-2.0 python3-gi-cairo gir1.2-pango-1.0 libglib2.0-bin pipewire \
  wireplumber ffmpeg bubblewrap libfaketime
pipx install --system-site-packages shotbox

--system-site-packages を指定すると、shotbox term と --a11y が使うシステムの PyGObject を利用できます。pip install shotbox でもインストールできます。または、チェックアウトから実行します：ln -s "$PWD/bin/shotbox" ~/.local/bin/shotbox。

shotbox doctor は、利用可能なものと不足しているものをそれぞれ 1 行で表示し、入手方法も示します。各コマンドとオプションに必要なものについては、必要条件を参照してください。

Python パッケージは不要です。標準ライブラリと各種ツールを使います。Wayland セッションでは追加のものが必要です。Wayland を参照してください。

Ubuntu の GitHub Actions ジョブでは、Action が自身と実行に必要なものを、使用するリリース（またはブランチ）の時点に合わせてインストールします。各機能に必要なものは名前を指定して要求できます（設定しない限りすべてオフ）。また、Ubuntu の AppArmor によって制限されている bubblewrap にサンドボックスを作成させます。

- uses: mishan/[email protected]
  with:
    a11y: true        # --a11y and `shotbox a11y`
    speak: true       # `shotbox a11y speak`: Orca, and what a11y installs
    term: true        # `shotbox term`
    # wayland, audio, record, gamepads and clock too
- run: shotbox shoot app.png --window 'My App' -- ./my-app

簡単な紹介

shotbox shoot app.png --window 'My App' -- ./my-app          # a picture, once it's up
shotbox shoot app.png --twice --window 'My App' -- ./my-app  # the same every time?
shotbox compare ref.png app.png --diff diff.png              # what changed, and where
shotbox run -- ./take-pictures.sh       # a script that waits, clicks and captures inside
shotbox exec --audio -- npx playwright test        # sealed, with no display
shotbox start --name ed --a11y          # a session to come back to
shotbox spawn --session ed -- gnome-text-editor
shotbox --session ed a11y click Open
shotbox --session ed capture open.png
shotbox stop ed

コマンド

コマンド	機能
shoot	プログラムを実行して待機し、画面を撮影します。--twice を指定すると、同じ結果になることを確認できます
run	隔離されたセッションでコマンドを実行し、その終了ステータスで終了します
exec	同じ処理をディスプレイなしで実行します。ヘッドレスブラウザーやテストスイートに使えます
start, spawn, stop, sessions	継続するセッション、その中のプログラム、プログラムの停止、セッション一覧表示を行います
term	撮影対象となるターミナルを起動します
wait	ウィンドウ、ポート、ファイル、画面の静止、画像、変化、ログの行を待ちます
capture	画面を撮影するか、連続撮影します
record	映像、音声、またはその両方を録画・録音します
key, type, click, move, scroll, drag	キーを押し、文字を入力し、ポインターを操作します。押したままにすることもできます
park, focus	ポインターを邪魔にならない場所に移動し、ウィンドウにキーボードのフォーカスを与えます
play	1つのクロックに合わせて、タイミングを指定した入力スクリプトを再生します
latency	描画内容がポインターにどれだけ速く追従するかを測定します
flicker	画面上でちらついたり点滅したりする部分を検出します
pad	仮想ゲームパッドを操作します
a11y, wait announce, wait node	アクセシビリティツリーを操作します。読み取り、lint、Tab キーの移動順序、名前によるクリック、コントラスト、アナウンス、表示するノードの指定ができます
compare	画像ごと、またはディレクトリごとに、異なるピクセル数を数えます
vision	色覚異常のある人に見える色で画像を表示します
listen	録音の音量、クリッピング、音切れを確認します
mcp	MCP 経由でエージェント向けのセッションを提供します
doctor	各コマンドに必要なものが何かを確認します

セッションで指定できるオプション、--wayland、--a11y、--audio、 --gamepads、--net loopback、--identity、--clock、--dark などについては、 セッションオプションをご覧ください。

隔離されるもの

セッションは、プログラムが誤ってデスクトップにアクセスするのを防ぎます。意図的にアクセスしようとするプログラムを防ぐものではありません。

• 環境は許可リストから再構築されます。HOME とすべての XDG ディレクトリは一時ディレクトリです。
• ディスプレイ、セッションバス、システムバスはセッション専用です。--a11y と --audio を指定すると、アクセシビリティバスとサウンドサーバーもセッション専用になり、サウンドサーバーの音声はどこにも出力されません。プリンターはありません（ただし、--net loopback を指定しない限り、localhost:631 の CUPS は利用できます）。--machine-bus を指定すると、マシンのシステムバスとプリンターを利用できます。
• bubblewrap でサンドボックスを作成できる場合（作成できない場合はその旨が通知されます）、マシンのサウンドデバイスやデスクトップの Wayland、PulseAudio、PipeWire、バスソケットには何も到達しません。
• --net loopback を指定しない限りネットワークにアクセスでき、--identity を指定しない限りユーザー名とホスト名が表示され、--clock を指定しない限り実時刻が使われます。
• 隔離されないもの：一時ホームの外にあるファイル、X サーバー、その他のプロセスです。

すべての詳細と、各オプションで対象となるもの、対象とならないものについては、docs/sealed.md をご覧ください。

アクセシビリティ

--a11y を指定すると、セッション専用のアクセシビリティ（AT-SPI）バスが起動し、スクリーンリーダーが読み上げる内容を確認できます。指定しない場合、セッションにアクセシビリティバスはありません。GTK にはバスを参照しないように指示されます。どちらの場合も、デスクトップのバスには触れません。

GTK、Qt、AccessKit のツールキット、Chromium を対象に、shotbox a11y はツリーを出力し、名前のない項目を検出するリントを実行し、Tab キーの移動順をたどり、名前でクリックしてコントラストを測定します。shotbox wait announce は読み上げられる内容を待ち、shotbox wait node はノードの表示を待ちます。コマンド、その仕組み、各チェックで分かることと分からないことについては、docs/accessibility.md をご覧ください。

Wayland

--wayland を指定すると、セッションは Wayland 環境になります。プログラムは Xvfb 上ではなく、ソフトウェア描画を行うヘッドレス sway 上で実行されます。--xwayland を指定すると Xwayland と DISPLAY が追加されるため、X クライアントを Wayland デスクトップ上と同じように実行できます。GTK プログラムの場合は、--env GDK_BACKEND=x11 を指定します。

sway と grim が必要です。--xwayland には Xwayland が、record には wf-recorder が必要です。インストールするには、sudo apt install sway grim xwayland wf-recorder を実行してください。sway を採用した理由、その仕組み、X11 との違いについては、docs/wayland.md をご覧ください。

ドキュメント

• コマンド：各コマンドとセッションオプション、それぞれに必要なもの、リソースの使用状況、時計について
• 封印されているもの
• レシピ：具体的な使用例
• GUI を操作する他のツールとの比較
• MCP：エージェントが利用できるツールと、その構築方法
• アクセシビリティ
• Wayland
• デスクトップとの違い：描画、ウィンドウマネージャー、アニメーション、言語、スケール、入力、測定
• ゲームパッド
• Python：ディスプレイ自体を操作するスクリプト向けの shotbox.Session と here()
• Node：Playwright を使ったブラウザチェック用のヘルパー
• 貢献方法：テスト
• 行動規範、 セキュリティおよび アクセシビリティ
• リリース
• 変更履歴

ライセンス

MIT。LICENSEをご覧ください。