bigarrow: để AI agent chỉ đúng nút cần bấm trên macOS

bigarrow là CLI macOS cho phép Claude Code và Codex vẽ mũi tên, khung và nhãn nổi trên màn hình. Công cụ hướng người dùng tới bước cần xác nhận mà không tự click, gõ phím hay chụp màn hình.

bigarrow: để AI agent chỉ đúng nút cần bấm trên macOS

Agent vừa sửa code, build bản phát hành và mở System Settings. Nhưng khi tới nút Allow, nó chỉ có thể in “hãy bấm Allow” trong terminal — nơi bạn có thể không còn nhìn tới.

bigarrow xử lý đúng khoảng trống đó: một CLI cho macOS để Claude Code hoặc Codex vẽ mũi tên lớn, khung đánh dấu và chỉ dẫn ngay trên màn hình. Tool không bấm thay người dùng; nó chỉ đúng vị trí để người dùng tự quyết định.

Đây là một cách trực quan hóa bước human-in-the-loop: khi agent phải dừng ở một thao tác cần sự xác nhận hoặc hướng dẫn của con người.

bigarrow là gì?

Theo README, bigarrow là công cụ dòng lệnh macOS viết bằng Swift, kèm skill cho Claude Code và Codex. Tool tạo một cửa sổ trong suốt nằm trên các cửa sổ khác, xuất hiện trên mọi màn hình và Space để hiển thị mũi tên hoặc bảng chỉ dẫn.

Các đặc tính được dự án nêu ra gồm:

Click-through: click vẫn đi tới ứng dụng bên dưới. Không làm thay đổi keyboard focus hiện tại. Không cần quyền macOS chỉ để vẽ overlay. Không có daemon, biểu tượng menu bar, tài khoản hay telemetry. Không click, gõ phím hoặc chụp màn hình. Mũi tên có thể tự biến mất.

Ranh giới này là điểm đáng chú ý: agent có thể hướng người dùng tới hộp thoại quyền, OAuth, passkey, CAPTCHA, thanh toán hoặc chữ ký, nhưng thao tác quyết định vẫn do người dùng thực hiện.

Cài đặt cho Claude Code và Codex

README hướng dẫn cài qua Homebrew:

bash brew install franzenzenhofer/tap/bigarrow bigarrow install-skill

Lệnh install-skill cài skill cho Claude Code tại ~/.claude/skills và Codex tại ~/.agents/skills.

Nếu build từ mã nguồn, dự án yêu cầu Xcode 16 trở lên và macOS 14 trở lên:

bash swift build -c release

Binary sau khi build nằm ở:

text .build/release/bigarrow

Dự án được phát hành theo giấy phép MIT.

Ví dụ: hướng dẫn bật một quyền trong System Settings

README minh họa tình huống mở khu vực Accessibility trong System Settings:

bash open "x-apple.systempreferences:com.apple.preference.security?PrivacyAccessibility"

Sau đó, bigarrow có thể đặt hai chỉ dẫn: một chỉ vào công tắc Terminal và một chỉ vào nút thêm ứng dụng.

bash bigarrow start --element TerminalToggle --app "System Settings" \ --text "Franz, switch this on: Terminal may control your Mac" --from right --color green --close-button

bigarrow start --element Add --role button --app "System Settings" \ --text "Not in the list? Plus. Then find it." --from bottom-right --style ring --color orange --shape zigzag --size S

Với một hộp thoại đơn giản hơn, lệnh có thể ngắn gọn:

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

Điểm chính không phải là tự động hóa cú click. Đây là cách để agent đưa chỉ dẫn từ terminal lên đúng ngữ cảnh giao diện mà người dùng đang thấy.

Không chỉ dành cho hộp thoại quyền

README còn đưa ra một số tình huống khác.

Chỉ đúng tab trong Chrome

Khi truyền ứng dụng dưới dạng App:tab title, README cho biết tool sẽ đưa cửa sổ lên trước và chọn tab rồi mới hiển thị overlay.

bash 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

Hướng dẫn nhiều bước trong giao diện

Với Keynote, các lệnh riêng có thể đánh dấu lần lượt các điều khiển như Animate, Add an Effect và Play. Đây là mẫu phù hợp cho các flow hướng dẫn thao tác trực quan: agent hiển thị từng điểm cần chú ý thay vì chỉ mô tả vị trí bằng chữ.

Đưa giá trị để người dùng tự dán

Khi phần text chứa {{value}}, README cho biết nhãn sẽ có nút copy. Ví dụ sau hướng người dùng tới trường PIN và cho phép copy giá trị trên nhãn:

bash bigarrow start --element "PIN code" --role textfield --app "Google Chrome:Acme sign-in" --from right \ --color blue --border-color yellow --text-color yellow \ --text "Franz, copy & paste the PIN {{482913}} here"

Tính năng này có thể hữu ích với mã dùng một lần, URL hoặc lệnh. Với dữ liệu nhạy cảm, team nên cân nhắc kỹ nội dung hiển thị trên màn hình trước khi đưa vào nhãn copy.

Giới hạn cần hiểu

bigarrow tự mô tả là không phải công cụ chú thích màn hình đa dụng, click bot hay screenshot tool. Nó chỉ tập trung vào việc “trỏ” tới một vị trí trên giao diện.

Tool định vị phần tử thông qua các tham số như --element, --app và, trong một số lệnh, --role. README cũng nêu --dry-run --json để xem vị trí tool sẽ trỏ tới, phục vụ việc kiểm tra tọa độ Accessibility hoặc Peekaboo.

Điều này khiến bigarrow phù hợp nhất khi agent cần kéo sự chú ý của người dùng tới một cửa sổ GUI cụ thể, thay vì chỉ in thêm một dòng hướng dẫn vào log.

Kết luận

Với developer dùng Claude Code hoặc Codex trên macOS, bigarrow là một primitive UI nhỏ nhưng khá rõ mục đích: agent chuẩn bị phần việc có thể làm, sau đó dùng overlay để chỉ chính xác bước người dùng cần tự xử lý.

Checklist trước khi thử:

Cài CLI và skill cho agent đang dùng. Dùng overlay cho bước cần xác nhận hoặc cần hướng dẫn trực quan. Để người dùng tự thực hiện các thao tác cấp quyền, xác thực và thanh toán. Cẩn trọng với dữ liệu nhạy cảm trong nhãn có nút copy. Kiểm tra --element, --app và --role trên đúng môi trường macOS của team.