big-arrow-on-the-screen
github.com/franzenzenhofer/big-arrow-on-the-screen- Category
- AI Agents
- Rank
- No. 1082Tools index
Previous survey · No. 1090 ·
- Pricing
- Open Source
- Type
- TOOL
- Use case
- Productivity & Collaboration
- Interfaces
- CLI · Agent Skill / Plugin
- GitHub
- 887 stars
- Latest release
- v0.6.1
- Date
About
A small macOS command line tool and agent skill that lets AI agents draw large arrows, boxes, and text on the screen. The overlays are click-through, do not take focus, and disappear on their own, so an agent can point at something on screen for the user without interrupting their work.
What it does
When a coding agent needs a person to press a button it cannot or should not press, it usually prints a request into a terminal nobody is watching. This tool lets the agent put a large arrow and a text sign on the Mac screen instead, aimed at a screen coordinate, a window, or a named button inside a running app. The overlay sits above every window on every display, lets clicks pass through, never takes keyboard focus, and removes itself after a time limit, when the agent process exits, or when the person replies. It never clicks, types or captures the screen.
Why it's ranked here
The scope is narrow and the build matches it. One Swift binary with a single dependency, Apple's argument parser, MIT licensed, installable from a Homebrew tap, with a ready-made skill for Claude Code and Codex. The details that matter for agent use are handled: documented exit codes for bad input, missing target and missing permission, a JSON mode on every command, and cleanup that does not rely on the agent remembering to stop. The code backs the README's claims about focus and click-through, which is where a tool like this usually fails.
What's good
Drawing needs no macOS permission at all; only pointing at a named button requires Accessibility access, and the error names the app that must be granted it rather than the tool. Placement is deterministic: the sign keeps clear of a fixed zone around the target, stays inside a margin from the screen edge, and avoids the signs of other live arrows before it accepts any overlap. A dry run reports where it would point without drawing, and a PNG mode renders the arrow to an image for docs. Signs can carry a copy button that puts a value on the clipboard.
Tradeoffs
It is macOS only, version 14 or later, so it does nothing for Linux or Windows agents. Targeting a button by its label depends on Accessibility permission for the terminal or agent host, and on the app exposing a sensible accessibility tree; an unlabelled control has to be hit by coordinate. The skill installer writes into both the Claude Code and Codex skill folders unless told otherwise. Distribution is a personal Homebrew tap rather than the main Homebrew repository. Two test suites are declared in the manifest, but what they cover is not shown by the source examined.
How to use it well
Install it on any Mac where an agent runs with a human nearby, and wire the stop command into the Claude Code hook that fires when the person submits a prompt, so arrows clear the moment they answer. Prefer the named-button target for permission dialogs and settings panes, and fall back to coordinates from a screenshot tool for unlabelled controls. It is a pointer, not an automation layer: anything that needs clicking or typing on the person's behalf needs a different tool.
Technical notes+
Package.swift (swift-tools-version 6.0, macOS 14) splits the code into BigArrowCore, BigArrowOverlay and BigArrowTargeting plus the bigarrow executable, with swift-argument-parser as the only dependency and two test targets, BigArrowCoreTests and IntegrationTests. Sources/BigArrowOverlay/OverlayPanel.swift builds a borderless nonactivating NSPanel at screenSaver level that joins all Spaces, ignores mouse events by default and refuses key and main status; OverlayApplication sets the accessory activation policy and pumps events with nextEvent instead of NSApplication.run, because finishLaunching would activate detached children and steal focus. Sources/BigArrowCore/Placement.swift scores eight approach directions across six reach scales, with a 120 pt keep-out square, a 24 pt margin and a 12 pt gap from other signs, falling back to a clamped least-overlap rect. Sources/BigArrowTargeting/ElementTarget.swift walks the AX tree of the matched app after Permissions.swift checks AXIsProcessTrusted; screen recording is checked via CGPreflightScreenCaptureAccess. Sources/bigarrow/BigArrow.swift maps all errors onto exit codes 0, 2, 3 and 4, and InstallSkillCommand.swift refuses to overwrite locally modified skill files without the force flag.
Observed
- License
- MIT
- Language
- Swift, tools version 6.0
- Platform
- macOS 14 or later
- Install surface
- Homebrew tap, or swift build from source
- Interfaces
- CLI with JSON output on every command, plus an agent skill for Claude Code and Codex
- Dependencies
- One: swift-argument-parser (declared in Package.swift)
- Permissions
- None to draw; Accessibility to target UI elements by label
- Exit codes
- 0 ok, 2 bad input, 3 target not found, 4 permission missing
- Tests
- Two test targets declared in Package.swift; test sources not read
Read from README.md, Package.swift, Sources/bigarrow/BigArrow.swift, Sources/bigarrow/PointCommand.swift, Sources/bigarrow/PointRunner.swift, Sources/BigArrowOverlay/OverlayController.swift, Sources/BigArrowOverlay/OverlayPanel.swift, Sources/BigArrowTargeting/Permissions.swift, Sources/BigArrowTargeting/ElementTarget.swift, Sources/BigArrowCore/Placement.swift, Sources/bigarrow/InstallSkillCommand.swift.
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.