bigarrow: macOS CLI Tool Lets AI Agents Draw Visual Pointers on Screen

Overview and Purpose

bigarrow is a macOS CLI and agent skill designed to let AI agents visually guide users by drawing large arrows, boxes, and text pointing to specific UI elements. Unlike standard annotation tools, it is built for programmatic control via shell commands, allowing agents to indicate targets like buttons or windows for tasks such as "Click Allow," 2FA prompts, or onboarding guidance. The tool operates with click-through behavior, meaning it does not steal focus from the active application, and requires no screen recording or drawing permissions for basic functionality.

Key Features and Integration

The tool supports integration with Claude Code and Codex via installable skills. Agents can use commands like bigarrow point to draw temporary indicators or bigarrow start for persistent displays. Key capabilities include:

• Targeting: Supports coordinates (--at X,Y), window titles (--window App:title), and accessibility elements (--element Label --app App).
• Visual Options: Customizable shapes (bend, straight, zigzag, spiral), styles (arrow, ring, box), colors, and sizes.
• Automation: Features like --follow to track moving elements, --until-click to dismiss on interaction, and --say for voice guidance.
• Agent Awareness: Automatically removes arrows when the owning agent process terminates or via hooks like bigarrow stop --hook.

Technical Implementation and Limitations

bigarrow is explicitly not an AI tool itself but a deterministic CLI utility. It uses Core Animation for rendering, maintaining low resource usage (1.4% CPU for pulsing arrows). It supports multi-display environments, Stage Manager, and Spaces.

• Permissions: Basic drawing requires no special permissions. However, targeting specific accessibility elements (--element) requires the shell (e.g., Terminal, VS Code) to have Accessibility permissions, not bigarrow itself.
• Browser Support: Works with Electron apps. Chrome support for --element requires launching with --force-renderer-accessibility or enabling VoiceOver.
• Scope: It is strictly for pointing and annotation. It cannot perform clicks, typing, or screen captures.

Development and Verification

The project was developed after a survey of 26 existing annotation tools revealed none supported programmatic, exit-code-driven pointing for agents. It includes 87 automated tests covering geometry, window-server interactions, and accessibility fixtures, verified on macOS 15, 26, and 27. The tool is released under the MIT license and can be installed via Homebrew (brew install franzenzenhofer/tap/bigarrow).