🎯 Big-Arrow-on-the-Screen: Visual Guidance for AI Agents

big-arrow-on-the-screen (aliased as bigarrow) is a specialized macOS command-line utility designed to bridge the communication gap between AI agents and human users. It allows agents to draw prominent arrows, boxes, and instructional text directly over any window on the screen.

The Problem: Your AI agent can handle complex monorepo refactors or explain the intricacies of monads, but when it needs you to click a specific button, it simply prints "please click Allow in the dialog" into a terminal window you might not even be looking at.

🛠️ Technical Overview

The tool functions by creating a single transparent window that sits atop every display and Space. It is designed to be non-intrusive: clicks pass straight through the overlay, and your keyboard focus remains undisturbed. Once the task is done, the arrow vanishes.

System Architecture

The "No" List

To ensure privacy and performance, the tool adheres to a strict philosophy:

• No background daemons
• No menu-bar icons
• No user accounts
• No telemetry
• No AI inside (Confirmed twice!)

Mathematically, the overhead is minimal: $\text{Resource Usage} \approx 0$ relative to standard macOS apps.

---

🚀 Real-World Applications

bigarrow is more than a gimmick; it provides actionable guidance in various scenarios.

1. System Permissions

When an agent needs you to grant accessibility rights:

# Open the specific settings pane
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"

# Point to the toggle
bigarrow start --element Terminal_Toggle --app "System Settings" \
--text "Franz, switch this on: Terminal may control your Mac" \
--from right --color green --close-button

# Point to the 'Add' button if the app is missing
bigarrow start --element Add --role button --app "System Settings" \
--text "Not in the list?" --from bottom-right --style ring --color orange --shape zigzag --size S

2. Step-by-Step Tutorials (e.g., Keynote)

You can chain commands to create a visual guide:

• Step 1: bigarrow start --element Animate --app Keynote --role radiobutton --text "1. Click Animate" --from right --style ring --color purple
• Step 2: bigarrow start --element " Add an Effect " --app Keynote --text "2. Add an Effect" --from right --style box --corners sharp --color "#FF9F0A" --shape straight
• Step 3: bigarrow start --element Play --app Keynote --role button --text "3." --from top --color teal --shape zigzag --size S

3. Helping Others (The "Mom" Use Case)

Guide a non-technical user through a PDF export in TextEdit:

# Point to the PDF menu
bigarrow start --element PDF --role button --app TextEdit \
--text "Mom, click PDF, then Save as PDF" --from bottom --color pink --border white-black

# Warn against the wrong button
bigarrow start --element Cancel --role button --app TextEdit \
--text "Not this one, Mom" --from bottom-right --color black --size S

4. Browser & File Management

• Chrome: Target a specific tab among many using --app "App:tab title".
  • Example: bigarrow start --app "Google Chrome:Sourdough" --element "Sourdough - Wikipedia" --role radiobutton --text "It's this tab, not the other 13" --from top --shape zigzag --color "#5856D6" --size L
• Finder: Distinguish between similar-looking icons.
  • Example: bigarrow start --element " icon view " --role radiobutton --app Finder --text "Not this one" --from top-left --style ring --color black --size S

---

🎨 Visual Customization

The developers spent an "unreasonable" amount of time perfecting the aesthetics to ensure visibility across white, grey, dark, and busy backgrounds.

Advanced Controls

• --close-button: Adds an X to the sign for manual dismissal.
• --follow: The arrow tracks the window/element if it moves.
• --until-click: Automatically closes once the target is clicked.
• --say: Uses system text-to-speech to read the sign aloud.
• --text-color, --edge-color, --close-color: Fine-grained color control.

📦 Project Metadata

• License: MIT
• Compatibility: macOS (tested on macOS 27)
• Integrations: Built-in skills for Claude Code and Codex.
• Quality Assurance: scripts/gallery.py was used to verify every possible combination of joints and junctions to ensure no visible seams.