bigarrow lets AI agents draw on-screen arrows to point at Mac buttons

bigarrow (the repository is called big-arrow-on-the-screen) is an open-source, MIT-licensed macOS command-line tool, plus a skill for Claude Code and Codex, that draws an arrow and a text sign on top of every window. The README opens with the problem: an AI agent can refactor a monorepo, write a migration and explain monads, but when it needs you to click one button it prints 'please click Allow in the dialog' into a terminal you are not looking at. bigarrow gives the agent a way to point at the control instead. The project was shared as a Show HN.

The mechanism is one transparent window above everything, on every display and every Space. Clicks go through it, your keyboard focus stays where it was, and the arrow removes itself. The README says drawing needs no macOS permission at all, and that the tool is a single Swift binary with no daemon, no menu-bar icon, no account, no telemetry and, in the authors' words, no AI inside. A typical call looks like this: bigarrow point --element "Allow" --app "System Settings" --text "Franz, click Allow: Ghostty may control your Mac".

The command line offers point for a one-shot arrow and start/stop for one that stays until stopped. Targets can be given as --at X,Y, --rect X,Y,W,H, --mouse, --window App[:title], --element Label --app App, or --peekaboo ID with a --snapshot see.json file. Coordinates are global top-left logical points, as Accessibility and Peekaboo report them. Passing --app first brings that app, window or Chrome/Safari tab to the front; if another app later covers the target, the arrow hides until it is visible again, and --no-raise turns the raising off. bigarrow elements --app X lists what --element can match, and bigarrow doctor shows permissions and displays. Every command takes --json, and the exit codes are 0 for ok, 2 for bad input, 3 for target not found and 4 for permission missing.

The look is configurable. Shapes are bend, straight, zigzag and spiral; styles are arrow, ring and box (rings and boxes are outlines, so the target stays visible); sizes are S, M and L; corners are round or sharp; colours are named or #RRGGBB; borders are shadow, white-black or black. A {{value}} placeholder in the sign becomes a copy button, --close-button puts an X in the sign, --follow tracks a window or element, --until-click ends the arrow on a click on the target, and --say speaks the sign aloud. Several arrows at once keep their signs out of each other's way.

The README lists what it is for: permission prompts and OAuth consent where the agent finds the button but must not or cannot press it; 2FA, CAPTCHAs, passkeys, payments and signatures, where the human decides; pasting a code, URL or command from the sign; calling you back to your desk with --say; showing how to do something in an app such as Blender by pointing at each control in turn; helping a relative on their Mac or over a screen share; recording demos and docs, including rendering to a PNG with --png; and debugging Accessibility or Peekaboo coordinates with --dry-run --json. The authors stress what it is not: a screen annotator, a click bot or a screenshot tool. It never clicks, types or captures. It only points.

Installation is brew install franzenzenhofer/tap/bigarrow, followed by bigarrow install-skill, which teaches Claude Code (~~/.claude/skills) and Codex (~~/.agents/skills). Building from source needs Xcode 16+ and macOS 14+. On token cost, the README says the skill description, the only part the agent always sees, is 182 tokens most of the time; the instructions are 1,398 tokens and load only when the agent decides to point, and pane ids and look flags add 1,008 more only when needed. It says nearly 400 GitHub stars arrived in the first two days.

Key facts

bigarrow is an MIT-licensed macOS command-line tool plus a skill for Claude Code and Codex that draws an arrow and a sign over every window so an agent can point a human at the control to click.
It only points: clicks pass through, keyboard focus is not taken, the arrow removes itself, and it never clicks, types or captures. Drawing needs no macOS permission, though some ways of finding the target do.
Targets can be a coordinate, rectangle, window, Accessibility element label or Peekaboo ID; commands take --json and return exit codes 0, 2, 3 and 4.
Install with brew install franzenzenhofer/tap/bigarrow and bigarrow install-skill; the skill description costs 182 tokens most of the time, with 1,398 more for the instructions when used.
The README claims 104 automated tests, 18 behaviour checks on a clean runner, CPU use of 1.4 % on a CI runner, and nearly 400 stars in two days.

Why it matters

Agents increasingly do real work on a Mac and sooner or later reach a step only a human may or should do: a permission dialog, a 2FA prompt, a payment. Today the usual result is a line of text in a terminal the user may not be watching. bigarrow turns that into a visible pointer on the actual control, with a sentence on the sign saying what the click does. It is a narrow idea, and the authors say they checked twenty-six existing tools before building it and found none that did this.

Who it affects

Mac users who run Claude Code or Codex and hit permission prompts, OAuth consent screens or sign-in steps mid-task. Also people who help family members on their Macs or over a screen share, and anyone recording demos or documentation who wants a scripted highlight. It is a macOS tool; the visible text mentions no Windows or Linux support.

How to use it

Install with brew install franzenzenhofer/tap/bigarrow, then run bigarrow install-skill to give the skill to Claude Code and Codex. Building from source needs Xcode 16+ and macOS 14+ and uses swift build -c release. You can try it by hand: bigarrow point --element "Allow" --app "System Settings" --text "Click Allow" for a label, or --at 760,500 for a coordinate. Run bigarrow doctor to see which permissions and displays it detects, and bigarrow elements --app X to list matchable labels. The skill teaches the agent when to point, how to pick a target, to write a full sentence on the sign, to use --say when you are away, and to stop once you have acted. The project is MIT licensed.

How solid is it

Everything here comes from the project's own README, so treat the figures as the authors' claims. They cite 104 automated tests (geometry, placement, joints, a golden image, copy buttons, recorded window-server, Accessibility and Peekaboo fixtures, and the real window server) and 18 behaviour checks on a clean runner. CI runs macOS 15 and the README says it also passed on macOS 26 and 27. The 1.4 % CPU figure was measured on a CI runner. The star count and the list of companies and universities behind the stars are the README's own claims, with no independent verification in the source. No release date or version number is given.

Risks and caveats

Finding a target by label depends on Accessibility. macOS grants the needed permissions to the app that started bigarrow (Terminal, iTerm2, Ghostty, VS Code, Claude), not to bigarrow itself, and a missing permission exits with code 4. Chrome is the awkward case: Accessibility targeting works only with --force-renderer-accessibility or VoiceOver on, and the authors say they verified in October 2026 that Chrome ignores the usual request; otherwise you point at page coordinates. Electron apps work. On the abuse question, the authors admit an agent could cover a Decline button, but argue that an agent that runs shell commands as you can already do far worse, so the tool gives it nothing new; they list tests for outlines keeping the target visible, signs staying clear of the target, click-to-remove and self-ending arrows. A click on the sign or shaft removes the arrow, while clicks on the target or near the head go to the app.

“It never clicks, types or captures. It only points.”

— bigarrow README