AI駆動のMacワークフローで人を誘導するビッグアローの使い方

画面上の大きな矢印が行うこと

big-arrow-on-the-screen（bigarrowとも呼ばれます）は、すべてのウィンドウの上に目立つ矢印と案内を表示するmacOS用コマンドラインツールです。コンピューター上のほとんどの作業を実行できる一方で、特定の判断を人間に委ねる必要があるAIエージェント向けに設計されています。

たとえば、エージェントは「システム設定」の「許可」ボタンを指し示したり、正しいブラウザウィンドウを特定したり、複数の手順が必要な操作を案内したりできます。主導権はユーザーにあります。bigarrowがクリック、入力、画面キャプチャを行うことはありません。

オーバーレイは通常のウィンドウ、ダイアログ、フルスクリーンアプリ、Spacesの上に表示されますが、キーボードフォーカスはすでにフォーカスを持っているアプリに残ります。対象上のクリックは下にあるアプリへそのまま通過します。矢印は表示時間が終了するか、所有プロセスが終了すると自動的に消えます。

エージェントが操作方法を説明し、人間が使う必要のある正確なコントロールに目印を付けられます。

使用する場面

bigarrowは、AIエージェントが人間に判断や操作を求める必要がある場面で役立ちます。代表的な例として、権限確認、OAuth同意画面、二要素認証、CAPTCHA、パスキー、支払い、署名、法的確認などがあります。

似たウィンドウやコントロールが複数表示されている場合にも、指示をわかりやすくできます。ユーザーに多数のウィンドウから探してもらう代わりに、エージェントが特定のアプリケーション、ウィンドウ、ブラウザタブを選択できます。

その他にも、アプリケーションの使い方を教える、リモートでサポートする、画面録画中にコントロールを強調する、別の自動化ツールが返した座標が正しいか確認するといった用途があります。

macOSにインストールする

このプロジェクトはmacOS 14以降に対応しています。最も簡単なインストール方法はHomebrewです。

brew install franzenzenhofer/tap/bigarrow

Claude CodeやCodexがこのツールをいつ、どのように使うか認識できるようにするには、エージェントスキルもインストールしてください。

bigarrow install-skill

これにより、Claude Code用のスキルは~/.claude/skillsに、Codex用のスキルは~/.agents/skillsにインストールされます。スキルをインストールせず、シェルからbigarrowを直接実行することもできます。

ソースからビルドする

自分でプロジェクトをコンパイルするには、Xcode 16以降を使用します。

swift build -c release

生成されたバイナリは.build/release/bigarrowにあります。アプリケーション自体はSwiftで書かれています。scripts/内のシェルファイルとPythonファイルは、スクリーンショットとテストに使用されます。

最初の指示コマンド

基本的なパターンは、アクセシビリティ要素を指す、座標を指す、停止するまで矢印を表示し続ける、の3つです。

ラベル付きコントロールを指す

bigarrow point --element "Allow" --app "System Settings" --text "Franz, click Allow: Ghostty may control your Mac"

--elementはラベルでコントロールを照合し、--appはそのコントロールを含むアプリケーションを指定します。案内にはユーザーに求める操作を説明するテキストを表示します。

座標を指す

bigarrow point --at 760,500 --text "Franz, click HERE"

座標には、macOS Accessibility、CGWindowList、Peekabooが報告するものと同じ、画面左上を原点とするグローバルな論理ポイントを使用します。長方形を指すこともできます。

bigarrow point --rect 600,400,240,80 --text "This is the area to review"

次の手順まで矢印を表示し続ける

bigarrow start --window "Safari:Inbox" --text "This window"
bigarrow stop

startはすぐに戻り、矢印を表示したままにします。stopで現在の矢印を消し、stop --allですべての矢印を消せます。

単発のpointコマンドは、デフォルトで8秒間表示されます。--durationで変更できます。startのデフォルトは300秒です。時間制限なしにするには--duration 0を使用します。

適切な対象を選ぶ

bigarrowは複数の対象指定方法に対応しています。

• --at X,Yは座標を指します。
• --rect X,Y,W,Hは長方形の範囲を強調表示します。
• --mouseは現在のマウス位置を指します。
• --window App[:title]はウィンドウを指します。
• --element Label --app Appはアクセシビリティ要素を検索します。
• --peekaboo ID --snapshot see.jsonは、Peekabooのsee --json出力に含まれる要素IDを使用します。

アプリケーションが公開しているコントロールを確認するには、次を実行します。

bigarrow elements --app "System Settings"

複数のディスプレイを使用する場合、--display Nを指定すると、座標と長方形の値が1台のディスプレイを基準にしたものになります。メインディスプレイの左または上に配置されたディスプレイについては、グローバル座標の負の値にも対応しています。

正しいウィンドウやブラウザタブを対象にする

--app App[:window or tab title]または--windowを指定すると、bigarrowは矢印を描画する前に、該当するアプリケーション、ウィンドウ、またはChrome/Safariのタブを前面に表示できます。これにより、正確な矢印が別の表示中のウィンドウ上に表示されるのを防げます。

bigarrow point --app "Google Chrome:Pull request" --text "Review this pull request"

ユーザーのウィンドウをそのままの位置に残したい場合は、--no-raiseを使用します。後から別のアプリケーションが対象を覆うと、対象が再び表示されるまで矢印は非表示になります。

矢印をわかりやすく便利にする

矢印の形状、スタイル、サイズ、角、色、動作をカスタマイズできます。

• --shape bend|straight|zigzag|spiralで矢印の経路を選択します。
• --style arrow|ring|boxで通常の矢印、枠線のみのリング、枠線のみのボックスを選択します。
• --size S|M|Lでサイズを変更します。
• --corners round|sharpで標識の角を設定します。
• --color red|orange|yellow|green|teal|blue|purple|pink|black|white|#RRGGBBでメインカラーを設定します。
• --border shadow|white-black|blackで枠線の表示方法を変更します。
• --border-color、--text-color、--edge-colorで個別の色をカスタマイズします。
• --close-buttonで標識にクリック可能なXを追加します。

たとえば、次のコマンドは対象を目立つ緑色のボックスで囲みます。

bigarrow point --at 760,500 --style box --color green --text "Review this control"

閉じるボタンは明示的に指定した場合のみ追加され、人がオーバーレイを直接閉じられるようにします。

bigarrow start --element "Save" --app "TextEdit" --close-button --text "Click Save when ready"

便利なインタラクションオプション

いくつかのオプションを使うと、オーバーレイをガイド付きワークフローに組み込めます。

• --followでウィンドウや要素に合わせて矢印を移動します。
• --until-clickで対象がクリックされた後に矢印を終了します。
• --sayで標識の内容を読み上げます。ユーザーが画面を見ていない可能性がある場合に便利です。
• --jsonでエージェントやスクリプト向けの機械可読な出力を提供します。

これにより、ガイド付きの手順で1つのコントロールを指し、ユーザーの操作を待って矢印を停止し、次のコントロールを指すことができます。このツール自体がクリックを実行することはありません。

権限について

オーバーレイの描画にmacOSの画面収録またはアクセシビリティの権限は必要ありません。ただし、対象の検索やアクティブ化の方法によっては権限が必要です。

• --at、--rect、--mouse、--window App、--peekaboo、--app Appには権限は必要ありません。
• --element、elements、--until-click、--app App:titleにはアクセシビリティの権限が必要です。
• --window App:titleでは、ウィンドウタイトルの読み取りに画面収録の権限が、ウィンドウを前面に出すためにアクセシビリティの権限が必要です。ただし、--no-raiseを使用する場合は前者のみ必要です。

macOSがこれらの権限を付与する対象は、bigarrowバイナリ自体ではなく、Terminal、iTerm2、Ghostty、VS Code、Claudeなど、bigarrowを起動したアプリケーションです。

診断コマンドを実行すると、関連する権限、権限を所有するアプリケーション、接続されているディスプレイを確認できます。

bigarrow doctor

必要な権限がない場合、コマンドはステータスコード4で終了し、関係するアプリケーションと設定パネルを示します。

自動クリーンアップを安全に使う

エージェントの処理後に矢印が残り続けないように設計されています。時間制限付きのpointコマンドは自動的に消えます。また、作成したエージェントプロセスが終了すると、利用可能な場合はCLAUDE_PIDまたはBIGARROW_OWNER_PIDを使って矢印も終了します。

Claude Codeのワークフローでは、bigarrow stop --hookをUserPromptSubmitフックとして使用し、人が応答したときにそのセッションの矢印を消去できます。明示的なクリーンアップコマンドは次のとおりです。

bigarrow stop
bigarrow stop --all

これらの安全策は、通常のクリーンアップ処理に到達する前に中断または置き換えられる可能性があるエージェントに役立ちます。

エージェントのワークフローでJSONと終了コードを使う

すべてのコマンドが--jsonを受け付けるため、結果をプログラムで確認しやすくなります。文書化されている終了コードは次のとおりです。

• 0：コマンドが正常に完了しました。
• 2：入力が無効です。
• 3：対象が見つかりません。
• 4：必要な権限がありません。

エージェントはこれらの結果を使って、別の対象指定方法で再試行するか、ユーザーに権限を求めるか、要求されたコントロールが見つからなかったことを説明するかを判断できます。

高度な対象デバッグ

アクセシビリティ、Peekaboo、その他のツールから取得した座標が正しいかどうかわからない場合は、ドライランを使用します。

bigarrow point --at 760,500 --dry-run --json

このコマンドはオーバーレイを描画せず、ツールが指し示す位置を報告します。ユーザーに表示する前に、座標変換、ディスプレイの選択、自動化の結果を検証するのに便利です。

Peekabooを別の対象ソースとして使うこともできます。PeekabooのJSONスナップショットを取得し、一致する要素IDを渡します。

bigarrow point --peekaboo ELEMENT_ID --snapshot see.json --text "この要素を確認してください"

Chromeでは、ページ要素を利用するためにChromeの--force-renderer-accessibilityフラグまたはVoiceOverが必要になる場合があります。Chrome独自のツールバーは、通常のアクセシビリティ経路から引き続き利用できます。ページのコンテンツが公開されていない場合は、代わりに座標を使用してください。

エージェントによるスキルの使い方

付属のスキルは、1つのAgent Skills互換SKILL.mdを通じてClaude CodeとCodexの両方をサポートし、Codex用のメタデータをagents/openai.yamlに含んでいます。このスキルは、エージェントが指し示すタイミング、対象の選択方法、標識に完全な文を書く方法、--sayを使うタイミング、ユーザーが操作した後に停止するタイミングを教えます。

実用的なエージェントの手順は次のようになります。

1. 人間による確認または支援が必要な操作を特定する。
2. ラベル、ウィンドウ、タブ、座標、矩形、またはPeekabooの対象を選択する。
3. ユーザーが何をすべきか、なぜそうするのかを正確に示す標識を書く。
4. 現在のレイアウトを維持することが重要でない限り、対象アプリケーションを前面に表示する。
5. 人間が操作または応答するまで待つ。
6. 次の手順に進む前に矢印を停止する。

このツールが行わないこと

bigarrowには意図的に制限があります。人向けの画面注釈ツールでも、クリックボットでも、スクリーンショットツールでもありません。画面をクリック、入力、キャプチャすることはありません。このツールの目的は、人間に判断と操作を委ねたまま、プログラムの指示を見える形にすることです。

リングとボックスのスタイルにはアウトラインを使用するため、対象を確認できます。標識は、スペースがある場合は対象から離れた位置に配置され、閉じるボタンを有効にすると、人間が矢印を消せます。これらの設計により、このツールは権限、認証、支払い、デプロイなどの慎重な操作に適しています。

まとめ

bigarrowは、曖昧なターミナルメッセージに頼ることなく、macOSベースのAIエージェントが簡単に操作を人へ戻せるようにします。Homebrewでインストールし、必要に応じてClaude CodeまたはCodexのスキルを追加したら、短いプロンプトにはpointを、手順を案内するワークフローにはstartとstopを使用してください。

ラベル、ウィンドウ、座標、矩形、マウス、Peekabooの対象に加え、スタイル、音声、JSON出力、自動クリーンアップ、マルチディスプレイをカスタマイズできるこのツールは、「ここをクリックしてください」という指示を正確な画面上の案内に変えながら、最終的な操作を人間の管理下に置きます。