big-arrow

big-arrow

bigarrow はクリックを妨げない、サイン付きの矢印を表示します。権限は不要で、フォーカスを奪うこともありません。対象そのものを指してください。ターミナル内の行は見落としやすいためです。

bigarrow 0.5.1 以降が必要です。bigarrow --version で古いバージョンが表示された場合は、まず brew upgrade franzenzenhofer/tap/bigarrow を実行してください。古いバイナリには card がなく、 {{value}} がプレーンテキストとして表示されます。

open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"
bigarrow start --element "Ghostty" --app "System Settings" --text "Franz, switch this on: Ghostty may record your screen" --say
# watch for the result (page changed, job continued, file appeared), then:
bigarrow stop

ルール

• 正確なペインまたは URL を自分で開き、人間に操作してもらうコントロールを 1 つだけ指してください。メニューを順に案内してはいけません。人間がクリックし、あなたは指し示します。
• サインには、操作を明記した完全な 1 文を書きます（「Franz、保存をクリックしてください」。単に「ここ」とは書きません）。クリックによって承認、付与、支払い、署名、送信、削除が行われる場合は、その結果も加えます。「Franz、支払いをクリックしてください：Hetzner に 49 EUR」。判断するのは人間です。事実はターミナルだけでなく、サインにも記載します。
• 人間が見ていない可能性がある場合は --say を使います。時間制限がある場合（コードの期限切れ、ページのタイムアウト、ジョブの待機中）は、--color red --say を使い、期限も伝えます。「Franz、2FA コードを今入力してください。有効期限は 60 秒です」。
• 貼り付けるもの（実行してはいけないコマンド、URL、コードなど）がある場合は、サインに {{value}} として記載します。人間にはコピー用ボタンに値が（波括弧なしで）表示され、1 回クリックするだけですべてコピーされ、矢印はそのまま残ります。貼り付け先も指し示します。「Franz、{{sudo xcodebuild -license accept}} をコピーして、ここに貼り付けてください」と伝え、貼り付けられたことを確認します。
• 1 ステップにつき矢印は 1 つです。ステップが完了したらすぐに bigarrow stop を実行します。矢印は 300 秒後、セッション終了時、または人間が応答したとき（下記のフック）にも自動で消えます。
• コピー用ボタンを除き、サインまたは軸をクリックすると矢印が消えます（対象へのクリックは透過します）。矢印が消えた場合は見られたということです。結果を確認し、矢印を再表示しないでください。依頼がない限り --close-button は使わないでください。

カード：値、秘密情報、回答

貼り付ける値が 1 つの場合は、サインに {{value}} チップを表示します。値が 2 つ以上ある場合、秘密情報がある場合、または質問がある場合は、コピー用ボタン付きのフローティングウィンドウであるキューカードを使います。フォーカスを奪うことはありません。

bigarrow card --title "Franz, log in to Hetzner" --app "Google Chrome" --field "[email protected]" \
  --secret "Password=keychain:hetzner/franz" --link https://console.hetzner.cloud --button "done=I'm in"
bigarrow wait          # blocks until an answer: {"result":"button","value":"done","copied":["User","Password"],...}

• 秘密情報をコマンドラインに記載してはいけません（ps ですべての人に見えてしまいます）。--secret には、pass:、keychain:<service>/<account>、op:、env:、file: のいずれかを指定するか、JSON カードに値を入れて stdin から渡します。秘密情報はドットで表示され、コピー時も隠されたままになり、クリップボードからは 30 秒後に消去されます。
• --ask "Question?"（入力式の回答）、--choice id=Label（2～6 個）、--button id=Label を指定します。wait は回答があると 0 で終了し、人間が回答せずにカードを閉じると 1 で終了します。その場合はターミナルで尋ねてください。
• 質問付きのカードは、すべての質問に回答すると自動で閉じます（--keep を指定すると X をクリックするまで表示されます）。answers にはすべての回答が含まれます。値だけのカードは、人間が X をクリックするまで表示されます。カードはセッションおよびプロンプトフックの終了後も残ります。不要になったら自分で閉じてください。bigarrow stop --pid <pid> または bigarrow stop --cards を実行します。
• 行で対象を指定できます。JSON カードで "point": {"element": "Password"} と指定すると、矢印がその値の貼り付け先を指し、人間が次の値をコピーするとそちらへ移動します。start ... --card card.json を実行すると、矢印とカードを同時に表示します。行の種類と JSON については、reference.md を参照してください。

対象

対象について分かっていること	使用方法
ネイティブアプリまたは Electron アプリ内のラベル	--element "Allow" --app "System Settings"
アプリまたはそのウィンドウのいずれか	--window "Safari" / --window "Safari:Inbox"
Chrome タブ内の位置	--rect x,y,w,h --app "Google Chrome:<tab title>"
スクリーンショット内の位置	--at X,Y --app "<App>"

アプリ内の対象を指定する場合は、必ず --app（または --window）を指定してください。対象のアプリが最前面に表示され、その上に別のアプリが重なると矢印は非表示になります。App:title はウィンドウタイトルに一致し、該当しない場合はタブに一致します。座標は、画面左上を原点とするグローバル座標です。Chrome ページ内で --element を使うには、Chrome を --force-renderer-accessibility 付きで起動する必要があります。そうでない場合は、getBoundingClientRect() の値を --rect に変換してください（reference.md）。判断がつかない場合は、bigarrow elements --app X --match "allow" または --dry-run を使います。

エラー

終了コード 2 は入力不正、3 は対象が見つからない場合（メッセージに存在する対象が表示されます）、4 は権限が不足している場合です。bigarrow doctor を実行してください。アクセシビリティ（--element、App:title、--until-click）と画面収録（--window App:title）の権限は、bigarrow ではなく、シェルを実行しているアプリ（Terminal、Ghostty、VS Code）に付与します。エラーに記載されたペインを開き（macOS 27 では、アクセシビリティは「デバイスコントロールとデータアクセス」です）、そのアプリのスイッチをオンにしてください。

詳細（ペイン ID、外観とタイミングのフラグ）：reference.md。

初回のセットアップ

~/.claude/settings.json："hooks": {"UserPromptSubmit": [{"hooks": [{"type": "command", "command": "bigarrow stop --hook"}]}]}