franzenzenhofer/big-arrow-on-the-screen: Let your AI brokers paint massive arrows, bins and textual content in your Mac display screen. One CLI, click-through, passed by itself. Ability for Claude Code and Codex. MIT. · GitHub

big-arrow-on-the-screen (bigarrow): one small macOS CLI and an agent ability. Click-through, by no means steals the main target, passed by itself. MIT.

Your AI agent can refactor a monorepo, write a migration and clarify monads, however when it wants you to click on one button it prints “please click on Allow within the dialog” right into a terminal you aren’t . bigarrow provides it a finger.

bigarrow level --element "Allow" --app "System Settings" --text "Franz, click on Allow"

A giant, pleasant arrow with an indication seems on high of all the pieces, factors on the factor, and goes away once more. It is click-through, it by no means steals your focus, it really works on each show and each Space, and it wants no permission in any respect to attract. It is one small Swift binary. There is not any daemon, no menu-bar icon, no account, no telemetry, and, we checked twice, no AI inside. It is an arrow.

Fair query. Arrows have existed since roughly the Paleolithic. Here is what modified: software program brokers now do actual work in your Mac, and so they hold hitting the identical wall, the half that solely a human might do.

• “Click Allow.” macOS permission prompts, OAuth consent screens, “Open with…?” dialogs. The agent can discover the button however should not, or can not, press it for you. It can now level at it.
• “Your flip.” 2FA codes, CAPTCHAs, passkeys, a fee affirmation, a signature, a authorized checkbox. The issues an agent ought to by no means click on by itself behalf. It factors, you determine, it continues.
• “It’s this window, not that one.” You have 14 Chrome home windows. The agent is aware of which one it means: --window "Google Chrome:Pull request". It even picks the fitting tab: --app "Google Chrome:Pull request".
• “I would like you, and you make espresso.” --say reads the signal aloud. Your Mac will actually name you again to your desk.
• Guided setups and onboarding. Walk a human via a settings pane step-by-step: begin, wait till they acted, cease, subsequent step. Like a product tour, minus the product.
• Remote assist. “No, the different gear icon.” Point at it as an alternative of describing it.
• Demos, screencasts, docs. Highlight what issues whereas recording, or render the arrow straight right into a PNG with --png for documentation.
• Debugging coordinates. Not positive your Accessibility, screenshot or Peekaboo coordinates are proper? Point at them and look. --dry-run --json tells you the place it would level with out drawing.

Staged with a impartial demo dialog and recorded with the true bigarrow on a clear CI runner (BACKDROP_ARGS=--cover scripts/funny-scenes.sh). The dialogs are pretend. The emotions are actual.

What it isn’t: a display screen annotator for people, a click on bot, or a screenshot software. It by no means clicks, varieties or captures something. It solely factors. Deliberately.

brew set up franzenzenhofer/faucet/bigarrow
bigarrow install-skill          # teaches Claude Code (~/.claude/expertise) and Codex (~/.brokers/expertise)

From supply: swift construct -c launch (Xcode 16 or newer, macOS 14 or newer), binary at .construct/launch/bigarrow.

bigarrow level --element "Allow" --app "System Settings" --text "Franz, click on Allow"   # by label
bigarrow level --at 760,500 --text "Franz, click on HERE"                                 # by coordinate
bigarrow begin --window "Safari:Inbox" --text "This window" && bigarrow cease            # till stopped

Every arrow ends by itself. Nobody has to scrub 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 (from Peekaboo’s see --json). Coordinates are international top-left logical factors, the area Accessibility, CGWindowList and Peekaboo report. --display N makes --at and --rect relative to at least one show.

An arrow is tied to the app it factors into. --app App[:window or tab title] (or --window) brings that app, window or Chrome/Safari tab to the entrance first, as a result of pointing at a window hidden behind your terminal is a particular sort of unhelpful; and whereas one other app covers the goal, the arrow hides and comes again with it. --no-raise leaves your home windows alone. bigarrow parts --app X lists what --element can match. bigarrow physician exhibits permissions, who owns them, and your shows.

Every command takes --json. Exit codes: 0 okay, 2 unhealthy enter, 3 goal not discovered, 4 permission lacking. Agents love exit codes. Humans tolerate them.

It is an arrow, so we spent an unreasonable period of time on the way it seems.

Real screenshots on a clear take a look at machine, six seems over white, macOS gray, darkish, black, pink and a busy net web page:

• --shape bend|straight|zigzag|spiral (zigzag for when it’s actually pressing; spiral loops as soon as across the signal earlier than it factors, for when it have to be inconceivable to overlook)
• --style arrow|ring|field; rings and bins are border-only, so you continue to see what’s below them
• --size S|M|L, --corners spherical|sharp
• --color pink|orange|yellow|inexperienced|teal|blue|purple|pink|black|white|#RRGGBB
• --border shadow|white-black|black: the default is a white border (darkish on gentle colors) with a drop shadow; white-black places a skinny black edge outdoors the white border as an alternative of the shadow; black is only a skinny black define
• Every color is yours: --border-color, --text-color, --edge-color, and for the X --close-color and --close-x-color. Left out, every picks a readable color itself
• --close-button places an X contained in the signal’s proper finish (white circle, X within the arrow color), the place it by no means covers the textual content or leaves the display screen
• --follow strikes with a window or ingredient, --until-click ends on a click on on the goal, --say speaks the signal
• Several arrows directly hold their indicators out of one another’s manner

The shaft grows out of the signal via a flared joint that by no means runs right into a rounded nook. scripts/gallery.py renders each mixture offscreen and zooms into each joint (junctions), as a result of a seam on the joint was, apparently, unacceptable.

Does it want Screen Recording or Accessibility?
Drawing wants neither. --element, parts, --until-click and entrance --window use Accessibility, which macOS grants to the app that runs your shell (Terminal, iTerm2, Ghostty, VS Code, Claude), by no means to bigarrow itself. bigarrow physician names that app, and exit code 4 tells the agent precisely what to ask you for. --window App:title reads window titles, which macOS 26 hides with out Screen Recording; --window App alone wants nothing.

Will it steal my focus whereas I’m typing?
No. That was the toughest bug within the mission: NSApplication.run() quietly prompts a course of that has no terminal, so indifferent arrows grabbed the main target. bigarrow pumps occasions itself as an alternative, and the assessments test that the frontmost app by no means adjustments.

Can I click on via it?
Yes, all over the place besides the signal and the shaft: a click on there removes the arrow (it dims just below the pointer to say so). A click on on the goal, or wherever close to the arrow’s head, goes straight via to the app. Clicking the arrow by no means takes the main target.

Multiple shows? Full-screen apps? Stage Manager? Spaces?
Yes, sure, sure, sure. Displays left of or above the primary one (damaging coordinates) included. Unplug a show whereas an arrow is on it and the arrow politely leaves. See the verification matrix.

How a lot CPU does a pulsing arrow value?
1.4 % measured on a CI runner. Core Animation does the work within the render server.

Does --element work inside net pages?
In Electron apps, sure. In Chrome, solely when Chrome runs with --force-renderer-accessibility (or VoiceOver is on); Chrome ignores the same old request to reveal web page content material, verified on Chrome in October 2026. Chrome’s personal toolbar all the time works. Otherwise level on the web page’s coordinates, which the ability explains.

Why not simply use [some screen annotation app]?
Those are for people drawing on screens. This is for applications pointing at issues, from a shell, with exit codes. Twenty-six instruments had been checked earlier than writing a line (research). None did this.

Is it AI?
No. It is the least clever a part of your AI stack, and pleased with it.

• 87 automated assessments: geometry, placement, joint smoothness, a golden picture, recorded window-server, Accessibility and Peekaboo 4.9.0 fixtures, and assessments towards the true window server (window degree 1000, clicks move via, focus by no means strikes, detach and cease timing). CI runs them on macOS 15; in addition they handed on macOS 26 and macOS 27.
• 17 behaviour checks on a clear runner (visual.yml): actual clicks on the X, --until-click, --follow, elevating (and --no-raise), hiding whereas coated, deciding on a Chrome tab, ending with the proprietor course of, cease --hook, --say, full-screen apps, Stage Manager, a Space change, a second show, a 2x show, unplugging a show mid-arrow, CPU. The demo GIF above is recorded by the identical workflow, on a desktop with nothing private on it.
• A recent agent given solely the ability and “present Franz the place the Reload button in Chrome is” discovered it by label and constructed the fitting command (transcript). It additionally discovered a bug, which is now a take a look at.

The ability in ability/big-arrow/ works for each Claude Code and Codex (one SKILL.md, Agent Skills format, plus brokers/openai.yaml for Codex). It tells the agent when to level, learn how to decide a goal, to write down a full sentence on the signal, so as to add --say if you end up most likely not wanting, and to cease after getting acted.

docs/plan/PLAN.md (purpose, structure, dangers), docs/plan/TICKETS.md (generated from docs/plan/tickets.json), docs/selections/, docs/analysis/ (verified info with hyperlinks), docs/verification/, docs/skill-tests/, CHANGELOG.md.

Peekaboo’s visualizer (https://github.com/openclaw/Peekaboo) and Nameplate (https://github.com/steipete/Nameplate) by Peter Steinberger confirmed the overlay window recipe and the agent-skill packaging. Neither attracts a pointing arrow with a label, which is the hole this mission fills. bigarrow reads Peekaboo’s see --json as an optionally available goal supply.

MIT. Point responsibly.