big-arrow-on-the-screen — 让 AI Agent 在 macOS 屏幕上"指出来"的标注工具

技能简介

big-arrow-on-the-screen（命令名 bigarrow）是一款面向 macOS 的命令行工具，同时打包为 Claude Code 与 Codex 的官方技能，专门解决 AI 智能体"看得见、做不了"的协作断点：当 Agent 在终端里已经替人类完成所有可执行步骤，唯独剩下"按一下 Allow""粘贴这个 PIN""点这个按钮"这种必须由人来完成的动作时，它会在屏幕上画出一支巨大、醒目、带文字说明的箭头、圆环或方框，直接指向目标 UI 元素。箭头随 Agent 进程一同消亡，不留后患。整个二进制为纯 Swift 编写，单文件、无守护进程、无菜单栏图标、无账号、无遥测、不含任何 AI 调用，绘图本身无需任何 macOS 权限。它既是一支箭头，也是一段"对话"：Agent 用它告诉你"现在轮到你了"。

核心能力

• 三大命令覆盖完整生命周期：point 一次性标注并自动消失（默认 8 秒），start 持续标注直到 stop 或超时（最长 300 秒），stop / stop --all / stop --hook 主动清除，进程随 Agent 一同死亡。
• 六种视觉样式与四种箭头形状：--style arrow|ring|box 三种标注框（ring/box 为半透明轮廓，不遮挡目标），搭配 --shape bend|straight|zigzag|spiral 四种箭头（zigzag 强调紧迫、spiral 绕一圈防错过）。
• 十种颜色与三种边框：内置红橙黄绿青蓝紫粉黑白 + 自定义 #RRGGBB，配合 --border shadow|white-black|black 三种边框（默认白边阴影、深色界面用 black 或 thin outline）。
• 七种目标定位方式：坐标 --at X,Y、矩形 --rect X,Y,W,H、鼠标当前位置 --mouse、窗口 --window App[:tab]、元素标签 --element Label --app App、Peekaboo 快照 ID、可访问性角色匹配 --role button|textfield|menubutton|radiobutton。
• 自动前置目标应用：--app "App[:tab]" 会先把指定 App 或 Chrome/Safari 标签拉到最前，目标被遮挡时箭头自动隐藏，目标再现时箭头自动显示。
• 声音朗读与可关闭按钮：--say 调用 macOS 朗读箭头上的文字，让离开座位的人被叫回来；--close-button 给人类一个"我点完了"的关闭入口。
• 复制粘贴模板：{{value}} 占位符自动渲染为可点击复制按钮，把 PIN、URL、命令直接交给人类。
• JSON 与精确退出码：每个命令都支持 --json 输出，退出码 0 ok / 2 参数错 / 3 目标未找到 / 4 权限缺失，便于 Agent 编程调用。
• 诊断工具：bigarrow elements --app X 列出可标注元素清单，bigarrow doctor 检查权限与显示器，--dry-run --json 仅返回"将会指向哪里"。

安装配置

• Homebrew 安装（推荐）：brew install franzenzenhofer/tap/bigarrow，安装完成后 bigarrow install-skill 自动把技能注册到 Claude Code 的 ~/.claude/skills/ 与 Codex 的 ~/.agents/skills/。
• 从源码编译：克隆仓库后 swift build -c release，需要 Xcode 16+ 与 macOS 14+，产物在 .build/release/bigarrow，纯 Swift 二进制，无运行时依赖。
• 零系统权限：绘图本身无需 macOS 任何授权；如需配合 Peekaboo / Accessibility 做元素匹配，可在"系统设置 → 隐私与安全性 → 辅助功能"中按需放行。

使用步骤

1. Agent 完成所有可执行动作后，调用 bigarrow point --element "Allow" --app "System Settings" --text "Franz, click Allow" --from right --color green 标注 macOS 授权弹窗的"Allow"按钮。
2. 调用 bigarrow start --element "PIN" --role textfield --app "Google Chrome:Acme sign-in" --text "Franz, copy & paste {{482913}} here" 在 Web 表单上同时显示箭头 + 复制按钮，把 PIN 推给人类。
3. 需要持续引导时用 bigarrow start --window "Safari:Inbox" --text "This window"，Agent 可中途 bigarrow stop --all 一次性清掉所有遗留箭头。
4. 完成时箭头随 Agent 进程自动消亡；若用户在 hook 中希望立刻清理，可在 Claude Code 的 UserPromptSubmit 钩子里挂 bigarrow stop --hook。

适用场景

• 权限弹窗与 OAuth 授权：macOS 的"允许 XXX 控制您的 Mac""允许辅助访问""允许屏幕录制"等系统弹窗，必须由真人点击。
• 2FA / CAPTCHA / 支付 / 签名：Agent 把活儿干完了，最后一公里只能交还给人。
• 远程协助父母与同事：在他们的 Mac 上画箭头比"屏幕共享里最上面的按钮，不是，是另一个上面"省一百倍口舌。
• 演示与文档录制：录视频时给操作加注释，或用 --png 直接渲染一张带箭头的静态截图放进 README。
• 调试坐标系统：配合 Peekaboo 或 Accessibility 调试时，--json 输出告诉开发者箭头实际会指向屏幕的哪个点。
• 多人协同办公：Agent 在同事电脑上演示操作步骤，每步配一支箭头，避免"我刚才说的那个按钮"。

适用人群

• 用 Claude Code / Codex / Cursor 长时间自动化工作的 AI 重度用户
• 需要远程帮父母或非技术同事处理 Mac 问题的开发者
• 录制产品演示视频、写带注释文档的技术作者
• 在 macOS 跑 CI / 自动化流程并涉及授权步骤的 DevOps 工程师

工作原理

bigarrow 用 Swift + AppKit 创建一个全屏透明的覆盖窗口，渲染在所有 App、Spaces 与菜单栏之上，但不接受任何鼠标点击（"click-through"），也不夺取键盘焦点。每条标注是一个独立子图层，包含文字、箭头/方框/圆环、复制按钮三部分，由 Core Animation 直接合成。Agent 通过 CLI 触发标注，CLI 把任务交给 Swift 二进制渲染并返回 JSON 结果；标注生命周期绑定到调用 CLI 的进程（通过 CLAUDE_PID 或 BIGARROW_OWNER_PID），进程退出时标注随之销毁。绘图逻辑完全本地、无网络、无 AI 调用，因此即使在断网环境也能稳定运行。

官方链接

• GitHub 仓库：https://github.com/franzenzenhofer/big-arrow-on-the-screen
• Show HN 原帖：https://news.ycombinator.com/item?id=50018817
• 许可证：MIT
• 技术栈：Swift + AppKit + Core Animation，单二进制，约 20 KB