bigarrow CLI: macOS AIエージェントのための視覚的ガイダンス

TL;DR – bigarrowの役割と重要性

bigarrowは、macOS用のシングルバイナリCLIツールです。画面上の任意のウィンドウや座標に対して、クリック可能な矢印、ボックス、および任意のテキストを描画し、自動的に消去します。描画に画面収録やアクセシビリティの権限を必要とせず、マルチディスプレイ、スペース、フルスクリーンアプリをまたいで動作します。また、正確な終了コードを返すため、AIエージェントが成功や失敗を確実に通知できます。エージェントに「クリック」ではなく「指し示す」手段を提供することで、多くの自動化ワークフローにおける人間のみが可能な最後のステップを橋渡しします。

コア機能 – エージェントが必要とする3つのコマンド

結論: エージェントは、矢印の指し示し、追跡、消去を行うための3つのシンプルなコマンドのみを必要とします。

コマンド	目的	例
`bigarrow point`	UI要素（ラベル指定）または画面座標に対して、オプションのキャプション付きで矢印を1つ描画します。	`bigarrow point --element "Allow" --app "System Settings" --text "Franz, click Allow"`
`bigarrow start` / `bigarrow stop`	エージェントが明示的に停止するかタイムアウトになるまで矢印を表示し続けます。	`bigarrow start --window "Safari:Inbox" --text "This window" && bigarrow stop`
`bigarrow point --at X,Y`	ラベルベースのターゲット指定が利用できない場合（アクセシビリティ非対応のWebページなど）に、生の座標を指定します。	`bigarrow point --at 760,500 --text "Franz, click HERE"`

すべてのコマンドは、--duration、--json出力、および一連のスタイル指定フラグ（形状、色、サイズなど）を受け付けます。終了コードは決定的です：0は成功、2は不正な入力、3はターゲットが見つからない、4は権限不足。

なぜ「クリック」ではなく「指し示す」のか？

結論: 指し示すことはユーザーの主体性を尊重し、セキュリティ上のリスクを回避しつつ、人間をガイドします。

権限ダイアログ – macOSのプロンプト（例：「許可」）を、エージェントがクリックを代行することなく強調表示できます。
機密性の高い操作 – 2FA、CAPTCHA、支払い確認、法的チェックボックスなどは、人間の管理下に置かれます。
ウィンドウの曖昧さ回避 – 複数のChromeウィンドウが開いている場合、--window "Google Chrome:Pull request"で正しいタブを選択してから指し示します。
音声キュー – --sayでキャプションを読み上げ、ユーザーの注意をデスクに引き戻します。
リモートアシスタンス – 「あの歯車のアイコン」と説明する代わりに、エージェントが直接指し示すことができます。
ドキュメント作成 – --pngで矢印をPNGとしてレンダリングし、静的なドキュメントやスクリーンキャストに利用できます。
デバッグ – --dry-run --jsonで描画せずに計算されたターゲットを報告し、座標検証に役立てます。

このツールは意図的にクリック、入力、スクリーンショットのキャプチャを行いません。純粋な視覚的キューです。

インストールと統合

結論: bigarrowはHomebrew経由でインストールするか、ソースからビルド可能です。また、Claude Code / Codex用のスキルがすぐに利用可能です。

brew install franzenzenhofer/tap/bigarrow
bigarrow install-skill   # registers the skill for Claude Code (~/.claude/skills) and Codex (~/.agents/skills)

ソースからビルドする場合: swift build -c release (Xcode 16+、macOS 14+が必要)。生成されたバイナリは .build/release/bigarrow に配置されます。

スタイルオプション – 矢印を目立たせる

結論: 豊富な視覚パラメータにより、どんな背景でも矢印が目立つように設定できます。

形状: bend（曲がり）、straight（直線）、zigzag（緊急）、spiral（ループ）。
スタイル: arrow（デフォルト）、ring、box（枠線のみ）。
サイズ: S, M, L。
角: round（丸）または sharp（鋭角）。
色: 名前付きパレット（red, orangeなど）またはカスタムの #RRGGBB。
枠線: shadow（デフォルト）、white-black、black。
閉じるボタン: --close-buttonで、クリックすると矢印を消去するXボタンを追加します。
動的挙動: --followで移動するウィンドウを追跡、--until-clickでクリック時に終了、--sayで音声合成をトリガーします。

プロジェクトには、すべての組み合わせをオフスクリーンでレンダリングし、矢印の接合部をズームしてシームレスな外観を確認するギャラリースクリプトが含まれています。

権限モデル – なぜ画面収録が不要なのか？

結論: 描画にはmacOSが追加の権限なしで許可する透明なオーバーレイウィンドウを使用します。ターゲット発見機能のみがアクセシビリティを必要とします。

描画 – 画面収録やアクセシビリティの権限は不要です。
ターゲット検索 – --element、elements、--until-click、--windowはアクセシビリティに依存します。これはmacOSが bigarrow 自体ではなく、シェルプロセス（Terminal、iTerm、VS Code、Claude）に対して許可を与えるものです。
bigarrow doctor – 必要な権限を持つアプリを報告し、権限が不足している場合はコード4で終了します。

この設計により、画面内容を密かにキャプチャすることを防ぎつつ、正確なUI要素の特定を可能にしています。

macOS環境全体での堅牢性

結論: 矢印はマルチディスプレイ、フルスクリーンアプリ、ステージマネージャ、スペースで動作し、ディスプレイの切断にも適切に対応します。

プライマリ画面の左/上に配置されたディスプレイの負の座標をサポートします。
矢印が表示されている間にディスプレイを取り外すと、矢印は適切に消去されます。
CIを通じてmacOS 15、26、27で検証済み。
CPU負荷は最小限（CIランナー上で約1.4%）で、Core Animationがレンダリングを処理します。

著者が強調する実用的なユースケース

結論: bigarrowはAI拡張ワークフローにおける具体的な課題に対処します。

権限プロンプト – エージェントが押せない「許可」ダイアログ。
2FA / CAPTCHA – エージェントが指し示し、人間が確認する。
ウィンドウ選択 – 多数のChromeウィンドウから曖昧さを排除する。
ガイド付きオンボーディング – 開始/停止セマンティクスを用いたステップバイステップツアー。
リモートヘルプ – 同僚に対して正しいUI要素を指し示す。
ドキュメント作成 – 注釈付きスクリーンショットを自動生成する。
座標デバッグ – アクセシビリティやPeekaboo座標の視覚的確認。

コミュニティのフィードバック – 主要コメントの統合

結論: ユーザーはコンセプトを評価していますが、安全性、ユーザビリティ、より広範な適用可能性について懸念を表明しています。

「『画面収録やアクセシビリティが必要か？』という部分を読もうとしたが、雑だった……『拒否』ボタンを隠すようなボックスを描画することを何が防いでいるのか？」 – @hn8726（描画がUI要素をブロックしないこと、サイン自体のみがクリック可能であることを明確化）

「矢印は『どこをクリックすべきか』を解決するが、『クリックすべきか』は解決しない。人間の意思決定の役割を減らしてしまう可能性がある。」 – @tilemarch（倫理的な境界を強調。ツールはクリックの自動化の手前で意図的に停止している）

「電話越しに母がドキュメントをダウンロードして印刷するのを手伝うのに最適だろう。」 – @arshxyz（エージェント以外のリモート支援のユースケースを示唆）

「正しいアプリを起動し、銀行振込の手順をユーザーにガイドしてくれるiPad版があれば、お金を払ってもいい。」 – @lbreakjai（クロスプラットフォームのUIアシスタントへの需要を示唆）

「READMEは技術者向けに書かれている。よりシンプルなUIがあれば普及が広がるだろう。」 – @usrbinbash（ドキュメントのアクセシビリティを指摘）

全体として、コミュニティは視覚的ガイダンスの価値を認めていますが、ユーザーの同意を維持するための明確な境界線の必要性を強調しています。

テストカバレッジと信頼性

結論: 広範な自動テストが、ジオメトリ、レンダリング、インタラクションの挙動を検証しています。

87個のユニットテスト：ジオメトリ、接合部の滑らかさ、ゴールデンイメージ比較、アクセシビリティおよびPeekabooフィクスチャとの統合をカバー。
17個の視覚的挙動チェック：実際のmacOSウィンドウサーバー上でのCI（クリック透過、フォーカス維持、マルチディスプレイ処理、CPU使用率など）。
エージェントスキルテスト：Claude Codeエージェントがスキルのみを使用してChromeの「再読み込み」ボタンを正常に特定。回帰テストとして追加されたバグを特定。

制限事項と未解決の疑問

結論: bigarrowは汎用的な画面注釈ツールではなく、UI自動化の代替にはなりません。

クリック、入力、スクリーンショットのキャプチャはできません。
Webページの要素ターゲット指定は、--force-renderer-accessibilityを付けて起動されたElectronアプリやChromeでのみ機能します。
ラベルベースのターゲット指定にはアクセシビリティに依存しており、それがない場合は座標を手動で指定する必要があります。
iOS/iPadOSは未サポートですが、コメントからコミュニティの関心は明らかです。

リポジトリが示唆する今後の方向性

結論: 著者はドキュメントの拡充、スキル形式の洗練、および追加の視覚的キューの検討を計画しています。

詳細な PLAN.md、DECISIONS/、RESEARCH/ ディレクトリがアーキテクチャとリスク評価の概要を示しています。
先行事例としてPeekabooビジュアライザーやNameplateがありますが、bigarrowは「矢印＋ラベル」のオーバーレイという隙間を埋めるものです。
将来的な拡張として、よりリッチなアニメーション、マルチエージェント調整、クロスプラットフォーム移植などが考えられます。

結論

bigarrowは、AIエージェントがmacOS上のUI要素をユーザーに「指し示す」ための軽量で権限不要な手段を提供します。曖昧な「このボタンをクリックして」というプロンプトを明確な視覚的キューに変え、ユーザーの主体性とシステムのセキュリティを維持します。その最小限のフットプリント、堅牢なテスト、柔軟なスタイリングにより、エージェント主導のワークフローへの実用的な追加ツールとなります。