📸

AIエージェントのための画面キャプチャツールを作った話

に公開
AI
Python
Cursor
開発効率化
Claude Code
tech

「今この画面を見てほしい」が伝わらない問題

ターミナル上でClaude CodeやCursorのようなAIエージェントと開発していると、「今この画面を見てほしい」という瞬間が意外と多く訪れます。

  • UIを軽く直したあと「レイアウトちゃんと合ってる？」
  • DevToolsのコンソールに出ているエラーを「これ、どういう意味？」
  • ダイアログや設定画面の「このボタンの下ってどうなってる？」

こういう「ちょっと画面を見てコメントしてほしい」系の相談は、テキストだけでは本当に伝わりません。「ヘッダーの右上に青いボタンがあって、その下に小さく……」なんて説明を文字で書いているうちに、「スクショ1枚撮った方が早いじゃん」となります。

しかし、ここで問題が発生します。

ターミナル上のAIエージェントには、画面を見せる簡単な方法がないのです。

Geminiの「画面共有」機能や、Google AI Studioの「Share your screen」のようなリアルタイム画面共有は、ブラウザベースのAIツールでは実現されています。しかし、ターミナルで動くAIエージェント（Claude Code、Cursor、Aider等）は、基本的にテキストベースのインターフェースなので、そのままでは画面を見せる手段がありません。

結果として、毎回以下のような手順を踏む必要があります:

  1. Win+Shift+S でスクリーンショットを撮る
  2. ペイントや画像ビューアーで確認
  3. ファイルを保存
  4. 保存先のフォルダを探す
  5. ファイルパスをコピー
  6. AIエージェントにパスを渡す

たった1枚の画面を見せるだけで、これだけの手順が必要になるのです。1日に10回、20回とスクショを撮っていると、この手間はかなりのストレスになります。

そして、もっと厄介な問題があります。

AIエージェント側から「画面を見たい」と思っても、自分では何もできないことです。

例えば、UIの修正を依頼した後、AIエージェントは「修正完了しました」と報告します。しかし、本当に正しく反映されているかを確認するには、人間が手動でスクリーンショットを撮ってAIに渡さなければなりません。AIエージェントが「自分で画面を見て確認する」ことができないため、修正の検証がボトルネックになるのです。

これは、AIエージェントの自律性を大きく制限する問題です。

解決策: AIエージェントが自分でスクショを撮れるようにする

この問題を解決するために、シンプルなPythonスクリプトを3つ作りました。

  • screen_capture_full.py: 画面キャプチャのメイン。モニターを自動認識して、必要な領域をPNGとして保存
  • image_quadrant_crop.py: 既存のPNGを4分割。AIが「もう一段階だけズーム」して見たいときに使う補助ツール
  • cleanup_snips.py: 溜まりがちなスクリーンショットを一括削除するクリーンアップ用スクリプト

構成はとてもシンプルで、前提は Windows + Python 3.x + Pillow だけです。

重要なのは、このツールはAIエージェントが自律的に使えるように設計されていることです。

システムプロンプトに「画面キャプチャツールの使い方」を書いておけば、ユーザーが「サブモニターの左上を見て」と指示したときに、AIエージェントは自分で適切なコマンドを組み立て、スクショを撮って確認します。人間が手動でスクショを撮る必要はありません。

なぜ「4分割」なのか

最初の設計では、「画面全体をキャプチャして、AIに渡す」という単純な方法を考えていました。しかし、実際に運用してみると、いくつかの問題が発生しました。

問題1: 画像サイズが大きすぎる

4K モニターで画面全体をキャプチャすると、1枚で 3840×2160 ピクセルの画像になります。これをAIに渡すと、処理が遅くなり、トークン消費も大きくなります。

問題2: 本当に見たい部分は画面の一部

UIレビューやエラー確認の場合、実際に見たいのは画面全体ではなく、「ヘッダーの右上」「DevToolsのコンソール」「ダイアログボックス」といった特定の領域です。画面全体を渡すと、AIは関係ない部分まで読み取ろうとして、本質的な情報を見逃すリスクがあります。

問題3: マルチモニター環境での混乱

ノートPC + 外付けモニター1枚という環境では、「全画面キャプチャ」を実行すると、2つのモニターが1枚の巨大な画像になります。これをAIに渡しても、「どのモニターのどの部分を見ればいいのか」が伝わりません。

これらの問題を解決するために、画面を4分割してキャプチャする方式を採用しました。

+--------+--------+
|   tl   |   tr   |  tl: 左上 (top-left)
|        |        |  tr: 右上 (top-right)
+--------+--------+  bl: 左下 (bottom-left)
|   bl   |   br   |  br: 右下 (bottom-right)
|        |        |
+--------+--------+

この方式により、ユーザーは「main の左下」「sub1 の右上」といった形で、見てほしい領域をピンポイントに指定できるようになります。

AIエージェント側も、「メインモニターの左下を見ればいい」と理解できるため、不要な情報を読み取らずに済みます。

さらに、もし4分割でも文字が小さすぎて読めない場合は、image_quadrant_crop.py で1段階だけズームできます。これにより、16分の1サイズの画像を生成して、細かい文字やアイコンまで確認できるようになります。

DPIスケーリング問題との戦い

Windows環境でマルチモニターを使っていると、DPIスケーリングという厄介な問題に直面します。

例えば、ノートPC内蔵ディスプレイが 150% スケーリング、外付けモニターが 100% スケーリングという設定の場合、Windows の仮想スクリーン座標と実際のピクセル座標がずれます。

最初のバージョンでは、すべてのモニターを Windows API から取得した座標で切り出していました。しかし、DPIスケーリングが混在する環境では、数十ピクセル単位のずれが発生し、「右上を撮ったはずなのに、少しだけ左にずれている」という問題が起きました。

この問題を解決するために、メインモニターだけは特別扱いする方式を採用しました。

# メインモニターは ImageGrab.grab() から直接4分割
if label == "main":
    img = ImageGrab.grab()
    width, height = img.size
    mid_x = width // 2
    mid_y = height // 2

    regions = {
        "tl": (0, 0, mid_x, mid_y),
        "tr": (mid_x, 0, width, mid_y),
        "bl": (0, mid_y, mid_x, height),
        "br": (mid_x, mid_y, width, height),
    }

ImageGrab.grab() は、Windows のDPIスケーリングを考慮して、実際に表示されている画像をそのままキャプチャします。そのため、この画像を単純に4分割すれば、DPIスケーリングの影響を受けずに正確な領域を切り出せます。

サブモニターについては、Windows の仮想スクリーン座標を使って切り出していますが、一般的な「ノートPC + 外付け1枚」構成では実用上問題ありません。モニターごとに極端なDPI設定が混在する特殊な環境では、数ピクセル単位のずれが出る可能性がありますが、UIレビュー用途なら許容範囲です。

AIエージェントから見た世界

このツールの最大のポイントは、AIエージェントが自律的に画面を確認できるようになることです。

従来のワークフローでは:

  1. ユーザーが「UIを修正して」と指示
  2. AIエージェントが修正を実装
  3. AIエージェントが「修正完了しました」と報告
  4. ユーザーが手動でスクショを撮ってAIに渡す
  5. AIが画面を確認して「問題ありません」または「ここが違います」と報告

このように、ステップ4で人間の手作業が必要でした。

しかし、このツールを導入すると:

  1. ユーザーが「UIを修正して」と指示
  2. AIエージェントが修正を実装
  3. AIエージェントが自分でスクショを撮って確認
  4. AIが「確認しました。正しく反映されています」と報告

人間の介入なしで、AIエージェントが修正→確認→報告まで完結します。

これは、AIエージェントの自律性を大きく向上させる変化です。

さらに、AIエージェントは「もう少しズームして確認したい」と判断したときに、自分で image_quadrant_crop.py を実行して、細部まで検証できます。

# AIエージェントが自律的に実行するコマンド例
python screen_capture_full.py main bl
python image_quadrant_crop.py "C:\...\screen_20251201_143025_main_bl.png" --cleanup

このように、AIエージェントは「どの領域を撮るべきか」「ズームが必要かどうか」を自分で判断し、適切なコマンドを実行します。

「スクショを撮る」ではなく「画面を見る」

このツールを使い始めてから、AIエージェントとのやりとりが大きく変わりました。

以前は、「スクショを撮って渡す」という作業が常に頭にあり、「画面を見せるのが面倒だから、テキストで説明しよう」と妥協することが多くありました。

しかし、今では「サブモニターの右上を見て」と言えば、AIエージェントが自分でスクショを撮って確認してくれます。スクショを撮る作業が完全に自動化されたことで、「画面を見せる」という行為のハードルが劇的に下がったのです。

結果として、UIレビューやエラー確認の精度が向上し、開発のスピードも上がりました。

実装の詳細

モニターをラベル付きで認識する

Windows API (EnumDisplayMonitors / GetMonitorInfoW) からモニター情報を取得し、次のようにラベル付けしています。

  • プライマリモニター: main
  • 2枚目: sub1
  • 3枚目以降: sub2, sub3 ...

これにより、「main の左下」「sub1 の右上」といった直感的な指定が可能になります。

コマンドインターフェース

実際に使うコマンドはだいたい次の3パターンです。

# すべてのモニターを4分割（main_tl, main_tr, ..., sub1_br ができる）
python screen_capture_full.py

# メインモニターの左下だけ
python screen_capture_full.py main bl

# サブモニターの左上だけ
python screen_capture_full.py sub1 tl

実行すると、指定したフォルダ（デフォルト: <SCRIPT_DIR>/../snips）に PNG が生成されて、パスが標準出力に1行ずつ出ます。

環境変数でカスタマイズ可能

保存先ディレクトリは環境変数 SCREENSHOT_SAVE_DIR で変更できます。

set SCREENSHOT_SAVE_DIR=C:\Users\YourName\Screenshots
python screen_capture_full.py

これにより、プロジェクトごとに保存先を分けることも可能です。

クリーンアップの自動化

テストや検証をしていると、スクリーンショットはどんどん溜まっていきます。そこで、cleanup_snips.py でまとめて掃除できるようにしました。

# 60分以上古いファイルのみ削除（デフォルト・推奨）
python cleanup_snips.py

# すべてのPNG/JPGを削除（⚠️ 注意: 必要なスクショも削除される）
python cleanup_snips.py --all --force

デフォルトでは60分以上古いファイルのみを削除するため、安全にクリーンアップできます。--all --force オプションを使うと全てのスクリーンショットが削除されるため、誤実行を防ぐために --force フラグが必須となっています。

これで、「テストセッションの最後に一度だけクリーンアップする」という習慣が作りやすくなります。

今後の可能性

このツールは、現時点では Windows 専用ですが、macOS / Linux 対応も可能です。macOS であれば screencapture コマンド、Linux であれば scrot や import コマンドを使って、同様の機能を実現できるはずです。

また、将来的には以下のような拡張も考えられます:

  • 特定のウィンドウだけをキャプチャ: 現在は画面全体または4分割ですが、特定のアプリケーションウィンドウだけを撮る機能
  • OCR統合: スクショを撮った後、自動的にテキストを抽出してAIに渡す
  • 動画キャプチャ: 静止画だけでなく、画面の動きを動画として記録し、AIに解析させる

しかし、現時点でも、「ターミナルのAIエージェントに画面を見せる」という基本的な問題は解決できています。

まとめ

  • ターミナル上のAIエージェントには、画面を見せる簡単な方法がなかった
  • 毎回手動でスクショを撮ってパスを渡す作業は、思った以上に面倒で非効率
  • AIエージェント自身が「画面を見たい」と思っても、自分では何もできなかった
  • screen_capture_full.py を使うと、AIエージェントが自分でスクショを撮って確認できる
  • 画面を4分割することで、見てほしい領域をピンポイントに指定できる
  • DPIスケーリング問題にも対応し、マルチモニター環境でも正確にキャプチャ可能
  • image_quadrant_crop.py で1段階だけズーム、cleanup_snips.py でクリーンアップまで自動化
  • 結果として、AIエージェントの自律性が大きく向上し、開発のスピードと精度が上がった

「AIエージェントに画面を見せたい」と思ったら、ぜひこのツールを試してみてください。

システムプロンプトの活用

このツールの真価は、システムプロンプトに組み込むことで発揮されます。

CLAUDE.md、agents.md、README.mdなどのシステムプロンプトファイルに、このツールの使用方法を記載しておけば、AIエージェントはユーザーからの指示を待たずに、自律的に画面キャプチャを実行できます。

詳細なシステムプロンプトのサンプルは、リポジトリ内の SYSTEM_PROMPT.md を参照してください。以下のような内容が含まれています:

  • 環境変数設定: PROJECT_ROOT を使ってプロジェクトごとに保存先を統一
  • 自動発火条件: UIデプロイ後、エラー確認時など、AIが自発的にスクショを撮るべきタイミング
  • 実行フロー: キャプチャ→確認→必要に応じてズーム→クリーンアップの一連の流れ
  • 禁止事項: 誤実行を防ぐためのガードレール（--all --force 必須化など）
  • トラブルシューティング: よくあるエラーと解決策

システムプロンプトを読むだけで、AIエージェントは以下のような判断を自律的に行えるようになります:

  1. どのモニターのどの領域を撮るべきか（main tl、sub1 br など）
  2. ズームが必要かどうか（4分割で読めなければ image_quadrant_crop.py で16分割）
  3. クリーンアップのタイミング（60分以上古いファイルのみ削除）

これにより、人間は「サブモニターの右上を見て」と一言指示するだけで、AIエージェントが適切なコマンドを組み立て、スクショを撮影し、内容を確認して報告してくれます。

リポジトリ

https://github.com/Tenormusica2024/ai-screen-capture-tools

GitHubで編集を提案

Discussion