bigarrow: a Mac overlay that gives an AI agent a finger on the screen

The arrow draws itself, then removes itself

big-arrow-on-the-screen, whose command is 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.

Those three properties are the whole design, and each of them answers a specific objection. An overlay that swallowed clicks would be a modal dialog, which is exactly the thing the tool exists to avoid. An overlay that stole keyboard focus would break whatever you were typing in. And an overlay that stayed on screen would be debris, so it cleans up after itself.

The use case is stated in one sentence near the top of the README, and it is the best sentence in the document. 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.

So the tool is a way for a text-only agent to address a human. It does not know what it is pointing at, it does not understand the interface, and it does not perform the click. It marks a place and says something, and the human does the rest.

That framing also explains the accessibility topic on the repository, and the 6-page PDF guide in docs/guides/allow-screen-recording/, where every screenshot in a written procedure is an arrow an agent drew. The tool is used to make a written instruction point at the right pixel.

It is MIT licensed, with the LICENSE file at the root of the repository, and the author notes that it is a skill for Claude Code and Codex, so the integration story is an agent runtime rather than a human running commands by hand.

One command, and the options that decide where the arrow lands

The example in the README is one line, and it shows the shape of the interface:

bigarrow point --element "Allow" --app "System Settings" --text "Franz, click Allow: Ghostty may control your Mac"

You name the element to point at, the application it lives in, and the words to show. The point command draws a single arrow immediately. The start command, used throughout the real use case examples, takes the same options plus a set of placement and style flags, and the examples show how wide those are:

bigarrow start --element Animate --app Keynote --role radiobutton --text "1. Click Animate" --from right \
  --style ring --color purple

The options in that one line cover four independent decisions. The element is matched by name, and a role narrows the match, with radiobutton and button and menubutton all appearing in the examples. The application is named, and the special form App:tab title raises the window and selects the tab first, which is what the Chrome example uses to point at one of fourteen tabs. The text is what the sign says. And then the appearance: --from picks the side the arrow comes from, with right, bottom-right, top, top-left and bottom all used, --style picks a ring or a box, --shape picks a zigzag or a straight shaft, --color takes a name or a hex value, and --size takes S or L.

There is also --close-button, which adds a close control to the sign, and --border and --corners for the box styling.

The end result is that two arrows can look completely different while pointing at the same button, which is the point. The print dialog example puts a pink arrow on the PDF button with a white and black border and a separate small black arrow on Cancel, and the Finder example points at the icon view button with a black ring and at the Group button with a green box, so the two candidate controls are visually distinguished rather than just labelled.

No permission, no daemon, no telemetry and no AI inside

The implementation claims are worth quoting because they are unusual for a tool that draws on top of your screen. 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, the README says, we checked twice, no AI inside. It is an arrow.

The absence of permissions is the load-bearing claim. A tool that draws an overlay on your screen sounds like it should require accessibility or screen recording permission, which on macOS means an approval prompt and a security review. The design avoids that by drawing in a window that is above other windows but not interactive, and by never needing to read what is on the screen: the element, the application and the role are all supplied by the caller as strings.

That is why the tool is described as a command line tool first and a skill second. The agent is the thing that knows which element it means, and bigarrow is the thing that turns that knowledge into a mark on the screen.

The repository matches the description. Sources/ holds the Swift, Tests/ the test suite, skill/ the agent skill, scripts/ the shell helpers, including scripts/real-scenes.sh which stages the real application scenes shown in the README, and docs/ the images, videos and guides. There is a Package.swift and Package.resolved for Swift Package Manager, a .swiftlint.yml for linting, a CLAUDE.md for the agent side, a THIRD_PARTY_NOTICES.md and a CHANGELOG.md.

The sign can carry a copy button, which is the part that changes the workflow

The copy and paste section is short and describes a feature that deserves more attention than it gets. A value written as {{value}} inside the sign becomes a copy button. Click, paste.

The example is a made-up sign-in page asking for a PIN, where a blue arrow with a yellow border points at the empty field and the sign says Franz, copy and paste the PIN 482913 here, the PIN on a yellow copy button. The second screenshot shows the same moment after the click, where the copy icon has become a check and the PIN is pasted into the field.

The reason this matters is the difference between an agent asking a human to retype a token and an agent handing the human a button. A password, a one-time code or a long identifier is exactly the case where an agent cannot proceed alone and a human should not have to type it by hand either.

Combined with the arrow, the two features compose into a pattern: the agent marks the field it wants filled and puts the value on a button next to it, the human clicks once, and the value is in place.

That is also where the tool's scope becomes clear. It does not read the clipboard and it does not type into the field, it offers a button. Whether the value reaches the field depends on the human clicking the right thing, which is the deliberate division of labour in a tool that explicitly says it contains no AI.

What it is actually for is the human in the loop

The README has a section on what the tool is actually for, and the answer is the whole point of the project.

The real use cases listed are ordinary Mac annoyances and permissions. There is the most complained-about Mac setting since 2023, clicking the wallpaper to show the desktop, which is fixed in six arrows. There is granting a permission in System Settings, where the guide opens Privacy and Accessibility and the arrows point at the Terminal toggle and then at the plus button for something not in the list. There is a three-step how-to in Keynote. There is helping Mom save a PDF from a print dialog. There is choosing the right tab out of fourteen in Chrome. There is telling Finder which of two grid icons is meant. And there is a written guide to allowing screen recording on a Mac, as a 6-page PDF in which every screenshot is an arrow an agent drew.

The common thread is that these are all cases where a human and an agent are working on the same machine at the same time, and the agent needs a human to act on a specific control in a specific window.

The real apps are real apps on a real Mac running macOS 27, and the scenes are staged by scripts/real-scenes.sh, which means the examples are reproducible rather than staged mockups.

There is also a FAQ section, a section on how the project knows it works, a section for agents and the humans who configure them, a plan section covering decisions and research, and a prior art section with thanks. The plan section is worth a look if you are evaluating the project, because it is where the design decisions and their reasons are collected.

Where bigarrow is the wrong tool

The first wrong fit is a machine that is not a Mac. This is a Swift binary for macOS, it draws a window on every display and every Space, and there is no version of the same idea for Windows or Linux in this repository. A cross platform agent workflow does not get a pointer from this tool.

The second is a workflow where the agent should click by itself. bigarrow is explicit that it contains no AI, that it does not understand the interface, and that it leaves the click to a human. If your automation is blocked only because the agent cannot drive the UI, an overlay that asks a person to do it is the wrong layer, and a real UI automation library is the right one.

The third is a high-stakes or unattended environment. An overlay that appears over every window and displays text is a screen that other people can read, and a machine that nobody is watching is a machine where an arrow pointing at a dialog is not going to be actioned.

The fourth is an element match that is not reliable. The tool matches by element name, by application, and by role, and the examples show both a plain match and a role refinement. In an application whose buttons change label with localisation or with state, the caller has to supply a name that will match, and the project does not claim to solve that.

The fifth is a shared or managed device. The tool has no account, no daemon and no telemetry, which is exactly why it is well behaved, and it also means there is no policy layer, no scoping to a project and no audit of what was pointed at. On a locked down machine none of that is needed.

On the state of the project: the tagged releases are v0.4.4 and v0.4.5 on 2026-10-09 and v0.4.6 on 2026-10-12, so the version is still below one and the numbering is moving quickly. The last push to the repository was on 2026-10-18 with the repository not archived, and the licence is MIT, with a THIRD_PARTY_NOTICES.md alongside the LICENSE file for the components it builds on.

Editorial conclusion

bigarrow fits an engineer running an agent that has to ask a human to click something, and who wants the request to appear on the screen instead of in a terminal they are not looking at. It does not fit a Windows or Linux workflow, and it does not fit anything where the agent should click by itself. Before adopting it, read the FAQ and the plan sections of the README, because the project is explicit that the arrow has no idea what it is pointing at and everything depends on the element and role the agent passes in.

Frequently asked questions

Official sources

1. franzenzenhofer/big-arrow-on-the-screen on GitHub
2. Issues
3. License: MIT
4. README
5. Releases