bigarrow: khi AI agent cần nhờ bạn bấm một nút

Các AI agent ngày nay có thể refactor cả monorepo, viết migration hay giải thích monad, nhưng khi cần bạn bấm đúng một nút thì chúng lại in dòng chữ "vui lòng bấm Allow trong hộp thoại" vào một cửa sổ terminal mà bạn không hề nhìn tới. bigarrow ra đời để giải quyết đúng khoảng trống đó.

bigarrow là gì?

bigarrow (tên đầy đủ big-arrow-on-the-screen) là một CLI nhỏ gọn dành cho macOS, kèm theo một kỹ năng (skill) dành cho AI agent. Công cụ này vẽ một mũi tên lớn kèm dòng chữ chỉ dẫn đè lên mọi cửa sổ khác, chỉ vào đúng vị trí cần bấm, rồi tự biến mất.

Điểm đặc biệt: mũi tên có thể click-through (bấm xuyên qua), không bao giờ cướp focus khỏi ứng dụng bạn đang dùng, hoạt động trên mọi màn hình và mọi Space, và không cần bất kỳ quyền hệ thống nào để vẽ. Đây là một binary Swift nhỏ, không có daemon, không có icon trên menu bar, không tài khoản, không telemetry — và theo tác giả khẳng định, không hề có AI bên trong nó.

Minh họa mũi tên bigarrow trên màn hình

Dùng để làm gì trong thực tế?

Nghe có vẻ đơn giản, nhưng bối cảnh đã thay đổi: các agent phần mềm giờ đây thực sự làm việc trên máy Mac của bạn, và chúng liên tục gặp cùng một rào cản — những phần chỉ con người mới được phép thực hiện.

• "Bấm Allow đi." Các hộp thoại cấp quyền của macOS, màn hình đồng ý OAuth, hộp thoại "Open with...?". Agent có thể tìm thấy nút nhưng không được phép — hoặc không thể — tự bấm. Giờ đây nó có thể chỉ vào đó.
• "Đến lượt bạn." Mã 2FA, CAPTCHA, passkey, xác nhận thanh toán, chữ ký, checkbox pháp lý. Những thứ mà agent tuyệt đối không nên tự bấm thay bạn. Nó chỉ, bạn quyết định, nó tiếp tục.
• "Là cửa sổ này, không phải cửa sổ kia." Bạn có 14 cửa sổ Chrome. Agent biết chính xác nó muốn cửa sổ nào thông qua tham số --window "Google Chrome:Pull request", thậm chí chọn đúng cả tab nhờ --app.
• "Tôi cần bạn, mà bạn đang pha cà phê." Tùy chọn --say sẽ đọc to dòng chữ trên biển báo, gọi bạn quay lại bàn làm việc.
• Hướng dẫn cài đặt và onboarding. Dẫn người dùng đi từng bước qua một bảng cài đặt: bắt đầu, chờ họ thao tác, dừng lại, chuyển bước tiếp theo — giống như một tour sản phẩm nhưng không cần sản phẩm.
• Hỗ trợ từ xa. "Không, cái biểu tượng bánh răng kia kìa." Chỉ thẳng vào thay vì mô tả bằng lời.
• Demo, screencast, tài liệu. Làm nổi bật phần quan trọng trong lúc ghi hình, hoặc render mũi tên thẳng ra file PNG bằng --png để đưa vào tài liệu.
• Debug tọa độ. Không chắc tọa độ Accessibility, screenshot hay Peekaboo có đúng không? Chỉ vào đó và xem. Tùy chọn --dry-run --json cho biết nó sẽ chỉ vào đâu mà không thực sự vẽ.

Cài đặt và các lệnh cơ bản

Cài đặt qua Homebrew rất đơn giản:

brew install franzenzenhofer/tap/bigarrow
bigarrow install-skill          # dạy Claude Code (~/.claude/skills) và Codex (~/.agents/skills)

Hoặc build từ mã nguồn bằng swift build -c release (yêu cầu Xcode 16 trở lên, macOS 14 trở lên), binary nằm tại .build/release/bigarrow.

Ba lệnh mà một agent cần nắm:

bigarrow point --element "Allow" --app "System Settings" --text "Franz, click Allow"   # theo nhãn
bigarrow point --at 760,500 --text "Franz, click HERE"                                 # theo tọa độ
bigarrow start --window "Safari:Inbox" --text "This window" && bigarrow stop            # kéo dài đến khi dừng

Mọi mũi tên đều tự kết thúc, nên không ai phải dọn dẹp giúp một agent đã "quên":

• Giới hạn thời gian — --duration 10 (mặc định 8 giây; start là 300 giây; --duration 0 là không giới hạn).
• Bắt đầu và dừng — bigarrow start ... trả về ngay lập tức; bigarrow stop (hoặc stop --all) xóa mũi tên.
• Agent biến mất — mũi tên kết thúc khi tiến trình agent đã vẽ nó thoát.
• Người dùng phản hồi — bigarrow stop --hook như một hook UserPromptSubmit của Claude Code sẽ xóa các mũi tên của phiên đó.
• Người dùng đóng nó — tùy chọn --close-button đặt dấu X có thể bấm trên biển báo.

Các kiểu mũi tên và hình dạng khác nhau

Yếu tố kỹ thuật đáng chú ý

Về quyền hạn: Việc vẽ mũi tên không cần quyền Screen Recording hay Accessibility. Các tính năng như --element, elements, --until-click dùng Accessibility — quyền mà macOS cấp cho ứng dụng chạy shell của bạn (Terminal, iTerm2, Ghostty, VS Code, Claude), chứ không phải cho bigarrow. Lệnh bigarrow doctor sẽ chỉ rõ ứng dụng nào đang giữ quyền, và mã thoát 4 cho agent biết chính xác cần hỏi bạn điều gì.

Không cướp focus: Đây là bug khó nhất của dự án. NSApplication.run() âm thầm kích hoạt một tiến trình không có terminal, khiến các mũi tên tách rời giành mất focus. bigarrow tự xử lý sự kiện thay vì dùng cơ chế đó, và các bài test kiểm tra rằng ứng dụng ở foreground không bao giờ thay đổi.

Hiệu năng: Một mũi tên nhấp nháy chỉ tốn khoảng 1,4% CPU đo trên CI runner, nhờ Core Animation xử lý phần render.

Đa màn hình: Hỗ trợ mọi cấu hình — màn hình bên trái hoặc phía trên màn hình chính (tọa độ âm), ứng dụng toàn màn hình, Stage Manager, Spaces. Rút phích cắm màn hình khi đang có mũi tên thì mũi tên sẽ lịch sự rời đi.

Kiểm thử và độ tin cậy

Dự án có 87 bài test tự động bao gồm hình học, vị trí đặt, độ mượt của khớp nối, ảnh golden, fixture của window-server, Accessibility và Peekaboo 4.9.0, cùng các test chạy trên window server thật (mức cửa sổ 1000, click xuyên qua, focus không bao giờ di chuyển). CI chạy chúng trên macOS 15, và chúng cũng đã vượt qua trên macOS 26 và macOS 27.

Ngoài ra còn có 17 kiểm tra hành vi trên runner sạch: click thật vào nút X, --until-click, --follow, nâng cửa sổ (và --no-raise), ẩn khi bị che, chọn tab Chrome, kết thúc theo tiến trình chủ, stop --hook, --say, ứng dụng toàn màn hình, Stage Manager, chuyển Space, màn hình thứ hai, màn hình 2x, rút màn hình giữa chừng, và CPU.

Điều thú vị: một agent mới chỉ được cấp kỹ năng và yêu cầu "chỉ cho Franz nút Reload trong Chrome" đã tìm ra nó theo nhãn và tự dựng đúng câu lệnh. Nó còn phát hiện một bug — bug đó giờ đã trở thành một bài test.

bigarrow không phải là gì?

Cần nói rõ để tránh hiểu lầm: đây không phải công cụ chú thích màn hình cho con người, không phải bot tự động click, và không phải công cụ chụp ảnh màn hình. Nó không bao giờ click, gõ phím hay chụp lại bất cứ thứ gì. Nó chỉ trỏ. Một cách có chủ đích.

Với những ai quan tâm đến làn sóng AI agent đang dần chiếm lĩnh quy trình làm việc trên máy tính cá nhân, bigarrow là một ví dụ thú vị về cách thiết kế "giao diện người–máy" ở tầng thấp nhất: không phải chatbot, không phải dashboard, mà chỉ là một mũi tên — thứ mà theo tác giả, "là phần kém thông minh nhất trong stack AI của bạn, và nó tự hào vì điều đó."

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