Show HN: Let your AI agents paint big arrows, boxes and text on your screen
big-arrow-on-the-screen (bigarrow) is a macOS command-line tool, plus a skill for Claude Code and Codex, that draws an arrow and a sign on top of every window. Clicks go through, your keyboard focus stays put, and the arrow removes itself. MIT licensed.
Real apps · What is it for? · Install · Commands · Looks · Creative arrows · Starred by · FAQ · How we know it works · For agents · Plan · Prior art · License
Your 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 it a finger.
One transparent window above everything, on every display and every Space. Drawing needs no macOS permission at all. One Swift binary: no daemon, no menu-bar icon, no account, no telemetry, and, we checked twice, no AI inside. It is an arrow.
Real apps on a real Mac (macOS 27), the real bigarrow, staged by scripts/real-scenes.sh.
“The most annoying change in Mac update history”, fixed in six arrows (MP4).
—app “App:tab title” raises the window and selects the tab first.
The whole guide as a 6-page PDF, every screenshot an arrow an agent drew. Download the PDF or read it here.
Fair question. Arrows have existed since roughly the Paleolithic. What changed: agents now do real work on your Mac, and sooner or later hit a step only a human may do, or one the human wants to learn.
Not a screen annotator, not a click bot, not a screenshot tool. It never clicks, types or captures. It only points. Deliberately.
From source: swift build -c release (Xcode 16+, macOS 14+), binary at .build/release/bigarrow. The binary is pure Swift; scripts/ only records screenshots and runs tests.
Every arrow ends by itself. Nobody has to clean up after an agent that forgot:
Targets: —at X,Y, —rect X,Y,W,H, —mouse, —window App[:title], —element Label —app App, —peekaboo ID —snapshot see.json. Coordinates are global top-left logical points, as Accessibility and Peekaboo report them; —display N makes them relative to one display.
—app App[:window or tab title] (or —window) first brings that app, window or Chrome/Safari tab to the front, because pointing at a window hidden behind your terminal is a special kind of unhelpful. If another app covers the target later, the arrow hides until it is visible again. —no-raise opts out. bigarrow elements —app X lists what —element can match; bigarrow doctor shows permissions and displays.
Every command takes —json. Exit codes: 0 ok, 2 bad input, 3 target not found, 4 permission missing. Agents love exit codes. Humans tolerate them.
It is an arrow, so we spent an unreasonable amount of time on how it looks.
Six looks over white, macOS grey, dark, black, red and a busy web page:
scripts/gallery.py renders every combination and zooms into every sign-to-shaft joint (junctions), because a seam at the joint was, apparently, unacceptable.
Fake dialogs, real bigarrow, clean CI runner (BACKDROP_ARGS=—cover scripts/funny-scenes.sh). The dialogs are fake. The feelings are real.
—color green, because some decisions are easy
—shape zigzag —color orange
—shape spiral: once around the sign, then to the button
—close-button, because the human gets the last word
three starts, one button, zero ambiguity
—style box —corners sharp, plus a lesson about macOS permissions
Nearly 400 stars in the first two days, from people whose GitHub profiles list Apple, NVIDIA, AMD, SAP, Salesforce, ServiceNow, Booking.com, Mercedes-Benz, SUSE, Oxide Computer, Posit, CoreWeave, Weights & Biases, OpenRouter, Metabase, InstaDeep, Benchling, Stainless and Under Armour, plus Stanford, Johns Hopkins, KTH and Oak Ridge National Laboratory.
Permissions? · In front without focus? · Steals my typing? · Click through? · Displays and Spaces? · CPU? · Web pages? · Can it trick me? · Token cost? · Why not an annotation app? · Is it AI?
Drawing: no. Some ways of finding the target do:
macOS grants these to the app that started bigarrow (Terminal, iTerm2, Ghostty, VS Code, Claude), never to bigarrow itself, so switch on that app. bigarrow doctor names it; a missing permission exits with code 4 and names the app and the settings pane.
On top and focused are two different things on macOS. The arrow sits at screen-saver level, above windows, dialogs and full-screen apps, but never becomes the active window.
No. That was the hardest bug in the project: NSApplication.run() quietly activates a process without a terminal. bigarrow pumps events itself, and the tests check that the frontmost app never changes.
Yes, everywhere except the sign and the shaft. A click there removes the arrow (it dims under the pointer to say so). Clicks on the target or near the head go straight to the app, without taking the focus.
Yes, yes, yes, yes. Negative coordinates included. Unplug a display while an arrow is on it and the arrow politely leaves. See the verification matrix.
1.4 % on a CI runner. Core Animation does the work in the render server.
In Electron apps, yes. In Chrome, only with help. Chrome needs —force-renderer-accessibility (or VoiceOver on); it ignores the usual request (verified October 2026). Chrome’s own toolbar always works. Otherwise point at page coordinates, which the skill explains.
Say, by covering the Decline button? Not beyond what it can already do. An agent that runs shell commands as you can do far worse, so bigarrow gives it nothing new. Still, each checked by a test: boxes and rings are outlines, so the target stays visible; the sign keeps clear of the target (or overlaps it as little as possible); a click on sign or shaft removes the arrow; every arrow ends by itself. And the skill makes the sign say what your click does.
182 tokens, most of the time. That is the skill’s description, the only part the agent always sees. The instructions, 1,398 tokens (Anthropic’s token-count API, Claude Opus 5.5), load only when it decides to point; pane ids and look flags (1,008 more) only when it needs them.
Those are for humans drawing on screens. This is for programs pointing at things, from a shell, with exit codes. Twenty-six tools were checked first (research). None did this.
No. It is the least intelligent part of your AI stack, and proud of it.
skill/big-arrow/ (Agent Skills format, plus agents/openai.yaml for Codex) teaches the agent when to point, how to pick a target, to write a full sentence on the sign, to —say it when you are away, and to stop once you acted.
docs/plan/PLAN.md, docs/plan/TICKETS.md (generated from tickets.json), docs/decisions/, docs/research/, docs/verification/, docs/skill-tests/, CHANGELOG.md.
Peekaboo (https://github.com/openclaw/Peekaboo) and Nameplate (https://github.com/steipete/Nameplate) by Peter Steinberger showed the overlay recipe and the skill packaging. Neither points with a labelled arrow. bigarrow reads Peekaboo’s see —json as a target source.
MIT. Point responsibly.
Let your AI agents paint big arrows, boxes and text on your Mac screen. One CLI, click-through, gone by itself. Skill for Claude Code and Codex. MIT.