屏幕上的大箭头（bigarrow）：一个小巧的 macOS CLI 和一个智能体技能。点击穿透，从不抢占焦点，自行消失。MIT。

CI License: MIT

Hacker News with five bigarrow arrows: the actual article is in here, finally an arrow bigger than this one, same design since 2007, today's thread already argued in 2014, not a lurker? click login

你的 AI 智能体可以重构 monorepo、编写迁移脚本并解释 monad，但当它需要你点击一个按钮时，它会打印“请在对话框中点击允许”输出到你根本没在看的终端里。bigarrow给它一根手指。

bigarrow pointing at a dialog's Allow button

bigarrow point --element “允许” --app “系统设置” --text “Franz，点击允许”

一个巨大、友好的箭头带着标牌出现在所有内容之上，指向那个东西，然后再次消失。它是点击穿透的，从不抢占你的焦点，它在每块显示器和每个 Space 上都有效，而且它需要完全不需要任何权限就能绘制。它是一个小巧的 Swift 二进制文件。没有守护进程，没有菜单栏图标，没有账户，没有遥测，而且我们检查了两遍，里面没有 AI。它就是一根箭头。

这到底是用来干什么的？

问得好。箭头大约自旧石器时代就已存在。变化在于：软件智能体现在能在你的 Mac 上做真正的工作，而它们总是撞上同一堵墙，那部分只有人类才能做的事。

  • “点击允许。”macOS 权限提示、OAuth 授权界面、“打开方式……？”对话框。智能体可以找到按钮，但不应、也无法替你按下它。现在它可以指向它。
  • “轮到你了。”2FA 验证码、CAPTCHA、通行密钥、支付确认、签名、法律复选框。这些是智能体绝不应代表自己点击的东西。它指向，你决定，它继续。
  • “是这个窗口，不是那个。”你有 14 个 Chrome 窗口。智能体知道它指的是哪一个：--window "Google Chrome:Pull request"。它甚至能选对标签页：--app "Google Chrome:Pull request"。
  • “我需要你，而你却在煮咖啡。” --say会朗读标牌。你的 Mac 会真的把你叫回桌前。
  • 引导式设置和入门引导。一步步带人类走过设置面板：start，等到他们操作完，stop，下一步。就像产品导览，只是没有产品。
  • 远程协助。“不，是另一个齿轮图标。”指向它，而不是描述它。
  • 演示、屏幕录制、文档。在录制时高亮重点，或者用--png把箭头直接渲染进 PNG 用于文档。
  • 调试坐标。不确定你的 Accessibility、截图或 Peekaboo 坐标是否正确？指向它们看看。--dry-run --json会告诉你它会指向哪里，而不实际绘制。

我们都经历过的那些情况

Staged with a neutral demo dialog and recorded with the realbigarrowon a clean CI runner (BACKDROP_ARGS=--cover scripts/funny-scenes.sh). The dialogs are fake. The feelings are real.
Delete node_modules? Yes. Obviously. Cookie banner: Franz, nobody reads these either
--color green --shape zigzag --color orange
2FA: This is where you sigh and find your phone Friday deploy: the agent strongly suggests Cancel
--color purple --close-button, because the human gets the last word
Three arrows, one Save button Grant Accessibility to Terminal, not to bigarrow
threestarts, one button, zero ambiguity --style box --corners sharp, plus a lesson about macOS permissions
Software update: Twirl. Then click.
--shape spiral: once around the sign, then to the button

What it is not: a screen annotator for humans, a click bot, or a screenshot tool. It never clicks, types or captures anything. It only points. Deliberately.

Install

brew install franzenzenhofer/tap/bigarrow
bigarrow install-skill          #teaches Claude Code (~/.claude/skills) and Codex (~/.agents/skills)

From source:swift build -c release(Xcode 16 or newer, macOS 14 or newer), binary at.build/release/bigarrow.

The three commands an agent needs

bigarrow point --element "Allow" --app "System Settings" --text "Franz, click Allow"   #by label
bigarrow point --at 760,500 --text "Franz, click HERE"                                 #by coordinate
bigarrow start --window "Safari:Inbox" --text "This window" && bigarrow stop            #until stopped

Every arrow ends by itself. Nobody has to clean up after an agent that forgot:
Time limit bigarrow point ... --duration 10(default 8 s;start300 s;--duration 0= no limit)
Start and stop bigarrow start ...returns at once;bigarrow stop(orstop --all) removes it
The agent goes away an arrow ends when the agent process that drew it exits (CLAUDE_PID, orBIGARROW_OWNER_PID)
The human answers bigarrow stop --hookas a Claude CodeUserPromptSubmithook clears that session's arrows
The human closes it --close-buttonputs a clickable X on the sign (opt-in)

Targets:--at X,Y,--rect X,Y,W,H,--mouse,--window App[:title],--element Label --app App,--peekaboo ID --snapshot see.json(from Peekaboo'ssee --json). Coordinates are global top-left logical points, the space Accessibility, CGWindowList and Peekaboo report.--display Nmakes--atand--rectrelative to one display.

An arrow is tied to the app it points into.--app App[:window or tab title](or--window) brings that app, window or Chrome/Safari tab to the front first, because pointing at a window hidden behind your terminal is a special kind of unhelpful; and while another app covers the target, the arrow hides and comes back with it.--no-raiseleaves your windows alone.bigarrow elements --app Xlists what--elementcan match.bigarrow doctorshows permissions, who owns them, and your 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.

Looks

It is an arrow, so we spent an unreasonable amount of time on how it looks.

Big arrows with signs: click here, sign here, over here, you are here, type your name, read this first, no the other one, click Allow

every border style and colour option: default white border with shadow, white-black, black, close button, custom border and text colours

Real screenshots on a clean test machine, six looks over white, macOS grey, dark, black, red and a busy web page:

default, white-black, black, close button, custom colours and a black arrow, each over six backgrounds

every style, shape, size and colour

  • --shape bend|straight|zigzag|spiral(zigzag for when it isreallyurgent; spiral loops once around the sign before it points, for when it must be impossible to miss)
  • --style arrow|ring|box; rings and boxes are border-only, so you still see what is under them
  • --size S|M|L,--corners round|sharp
  • --color red|orange|yellow|green|teal|blue|purple|pink|black|white|#RRGGBB
  • --border shadow|white-black|black: 默认是白色边框（在浅色上为深色）加投影；white-black在白色边框外加上一条细黑边，而不是投影；black只是一个细黑轮廓
  • 每种颜色都由你决定：--border-color，--text-color，--edge-color，以及用于 X 的--close-color和--close-x-color。若省略，每个都会自行选取一种可读的颜色
  • --close-button在标志的右端内部放一个 X（白色圆圈，X 为箭头颜色），它永远不会遮住文字或移出屏幕
  • --follow随窗口或元素移动，--until-click在点击目标时结束，--say朗读该标志
  • 多个箭头同时出现时，各自的标志会互相避开

箭杆从标志中长出，通过一个外扩的接头，且永远不会撞上圆角。scripts/gallery.py在离屏渲染每一种组合，并放大每一个接头（接合处），因为接头处的接缝显然是不可接受的。

常见问题

它需要屏幕录制或辅助功能权限吗？绘图两者都不需要。--element，elements，--until-click和front --window使用辅助功能权限，macOS 会将其授予运行你 shell 的应用（Terminal、iTerm2、Ghostty、VS Code、Claude），而绝不会授予bigarrow它自身。bigarrow doctor会指出该应用的名称，而退出码 4 会准确告诉智能体该向你请求什么。--window App:title会读取窗口标题，而 macOS 26 在没有屏幕录制权限时会隐藏这些标题；--window App单独使用则什么都不需要。

我打字时它会抢走我的焦点吗？不会。那是这个项目中最难的 bug：NSApplication.run()会悄悄激活一个没有终端的进程，于是分离的箭头抢走了焦点。bigarrow改为自行泵送事件，而测试会检查最前面的应用从未改变。

我能点击穿透它吗？可以，除了标志和箭杆之外的任何地方：点击那里会移除箭头（指针下它会略微变暗以示提示）。点击目标，或箭头头部附近的任何地方，会直接穿透到应用。点击箭头永远不会夺取焦点。

多显示器？全屏应用？台前调度？空间？是，是，是，是。包括主显示器左侧或上方的显示器（负坐标）。当箭头位于某个显示器上时拔掉该显示器，箭头会礼貌地离开。参见验证矩阵。

一个脉动箭头消耗多少 CPU？在 CI runner 上测得 1.4 %。Core Animation 在渲染服务器中完成工作。

是否--element能在网页内工作？在 Electron 应用中，可以。在 Chrome 中，只有当 Chrome 以--force-renderer-accessibility（或 VoiceOver 已开启）；Chrome 会忽略通常的暴露页面内容的请求，已于 2026 年 10 月在 Chrome 上验证。Chrome 自带的工具栏始终有效。否则就指向页面的坐标，技能中有说明。

为什么不直接用[某个屏幕标注应用]？那些是给人用来在屏幕上画东西的。这个是给程序用的，从 shell 里指向东西，带退出码。写第一行代码之前检查了 26 个工具（研究）。没有一个能做到。

它是 AI 吗？不是。它是你 AI 技术栈里最不智能的部分，而且引以为傲。

我们如何知道它有效

  • 87 个自动化测试：几何、放置、关节平滑度、一张黄金图像、录制的窗口服务器、Accessibility 和 Peekaboo 4.9.0 夹具，以及针对真实窗口服务器的测试（窗口层级 1000、点击穿透、焦点从不移动、分离和停止计时）。CI 在 macOS 15 上运行它们；它们在 macOS 26 和 macOS 27 上也通过了。
  • 在干净 runner 上的 17 项行为检查（visual.yml）：对 X 的真实点击，--until-click，--follow，提升（以及--no-raise），在被覆盖时隐藏，选择一个 Chrome 标签页，以属主进程结束，stop --hook，--say，全屏应用、Stage Manager、Space 切换、第二块显示器、2x 显示器、在箭头中途拔掉显示器、CPU。上面的演示 GIF 由同一工作流录制，在一台没有任何个人内容的桌面上。
  • 一个全新的智能体只拿到技能和“给 Franz 指出 Chrome 里 Reload 按钮在哪”，就通过标签找到了它并构建了正确的命令（记录）。它还发现了一个 bug，现在已成为一个测试。

给智能体（以及配置它们的人类）

技能位于skill/big-arrow/对 Claude Code 和 Codex 都适用（一个SKILL.md，Agent Skills 格式，外加agents/openai.yaml给 Codex）。它告诉智能体何时指向、如何选择目标、在标牌上写一个完整句子、在你可能没看的时候加上--say，以及在你操作之后stop。

计划、决策、研究

docs/plan/PLAN.md（目标、架构、风险），docs/plan/TICKETS.md（生成自docs/plan/tickets.json），docs/decisions/，docs/research/（带链接的已验证事实），docs/verification/，docs/skill-tests/，CHANGELOG.md。

先前工作和致谢

Peekaboo 的可视化器（https://github.com/openclaw/Peekaboo）和 Nameplate（https://github.com/steipete/Nameplate）由 Peter Steinberger 制作，展示了叠加窗口的做法和智能体技能的打包方式。两者都没有绘制带标签的指向箭头，而这正是本项目填补的空白。bigarrow读取 Peekaboo 的see --json作为可选的目标源。

许可证

MIT。请负责任地使用。