mcpField
B
big-arrow

big-arrow

github.com/franzenzenhoferProductivity86612 installsUpdated 2w ago
Repository

About big-arrow

big-arrow is a command-line skill for guiding people through macOS interface actions with a click-through arrow and cue cards. It supports pointing to controls, presenting copyable values, and collecting answers without taking focus.

Key features

  1. 01Click-through arrows with action labels
  2. 02Target app controls, windows, and screen regions
  3. 03Cue cards with values, secrets, and questions
  4. 04Copy buttons and human response waiting
  5. 05Automatic arrow dismissal and stop controls

Use cases

  1. 01Point out a specific control for a person to click
  2. 02Show a paste-ready command or URL
  3. 03Collect login details or answers through a card
  4. 04Guide a time-sensitive action with a spoken prompt

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/franzenzenhofer/big-arrow-on-the-screen --skill big-arrow

After installing, type/big-arrowin Claude Code to confirm it loaded.

Bundled filesagents/openai.yamlreference.md

Details

From the project README

big-arrow

bigarrow draws a click-through arrow with a sign, needs no permission and never takes the focus. Point at the thing itself, a line in the terminal is easy to miss.

Needs bigarrow 0.5.1 or newer. If bigarrow --version prints an older one, run brew upgrade franzenzenhofer/tap/bigarrow first: an old binary has no card and prints {{value}} as plain text.

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

Rules

  • Open the exact pane or URL yourself, then point at the one control left for the human. Never walk them through menus. The human clicks; you point.
  • The sign is one full sentence naming the action ("Franz, click Save", never "here"). When the click approves, grants, pays, signs, sends or deletes, add what happens: "Franz, click Pay: 49 EUR to Hetzner". The human decides; the facts go on the sign, not only in the terminal.
  • --say when the human may not be looking. Time-critical (code expires, page times out, job waits): --color red --say and say by when: "Franz, enter the 2FA code now, it expires in 60 s".
  • Something to paste (a command you may not run, a URL, a code): put it on the sign as {{value}}. The human sees the value on a copy button (no braces); one click copies all of it and the arrow stays. Point at where it goes: "Franz, copy {{sudo xcodebuild -license accept}} and paste it here", then check that it was pasted.
  • One arrow per step; bigarrow stop the moment the step is done. Arrows also end alone: after 300 s, when your session exits, when the human answers (hook below).
  • A click on the sign or shaft, except a copy button, removes the arrow (target clicks pass through). A removed arrow was seen: check the result, do not redraw. Skip --close-button unless asked.

Cards: values, secrets, answers

One value to paste: a {{value}} chip on the sign. Two or more values, any secret, or a question: a cue card, a floating window with copy buttons that never takes the focus.

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"],...}
  • Secrets never go on the command line (ps shows it to everyone): --secret takes a source, pass:, keychain:<service>/<account>, op:, env:, file:, or put the value in a JSON card on stdin. They show as dots, copy as concealed and leave the clipboard after 30 s.
  • --ask "Question?" (typed reply), --choice id=Label (2 to 6), --button id=Label. wait exits 0 for an answer, 1 when the human closed the card without one: then ask in the terminal.
  • A card with questions closes itself once every question is answered (--keep keeps it until the X); the reply's answers has them all. A card with only values stays until the human's X. It survives your session and the prompt hook: close it yourself when it is no longer needed, bigarrow stop --pid <pid> or bigarrow stop --cards.
  • A row can point: in a JSON card, "point": {"element": "Password"} aims the arrow at where that value goes, and it moves on when the human copies the next one. start ... --card card.json shows an arrow and a card together. Row types and JSON: reference.md.

Targets

You knowUse
A label in a native or Electron app--element "Allow" --app "System Settings"
An app or one of its windows--window "Safari" / --window "Safari:Inbox"
A spot inside a Chrome tab--rect x,y,w,h --app "Google Chrome:<tab title>"
A spot in a screenshot--at X,Y --app "<App>"

Always pass --app (or --window) for a target inside an app: it is raised first and the arrow hides while another app covers it. App:title matches a window title, else a tab. Coordinates are global top-left points. Inside a Chrome page --element needs Chrome started with --force-renderer-accessibility; otherwise convert getBoundingClientRect() to --rect (reference.md). Unsure? bigarrow elements --app X --match "allow" or --dry-run.

Errors

Exit 2 bad input, 3 target not found (the message lists what exists), 4 permission missing: run bigarrow doctor. Accessibility (--element, App:title, --until-click) and Screen Recording (--window App:title) belong to the app running your shell (Terminal, Ghostty, VS Code), never to bigarrow. Open the pane the error names (macOS 27: Accessibility is "Device Control and Data Access") and point at that app's switch.

More (pane ids, look and timing flags): reference.md.

Setup once

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

Comments

Markdown supported