bigarrow, AI 에이전트용 macOS 화면 지시 CLI 도구 공개

개요 및 목적

bigarrow는 AI 에이전트가 화면의 특정 UI 요소를 가리키기 위해 큰 화살표, 상자, 텍스트를 그릴 수 있도록 설계된 macOS CLI 도구이자 에이전트 스킬이다. 기존 주석 도구와 달리 셸 명령어를 통한 프로그래밍 방식 제어를 지원하며, '허용 클릭'이나 2FA 프롬프트, 온보딩 안내 등 버튼이나 창을 지시하는 작업에 활용된다. 이 도구는 클릭-스루(click-through) 방식으로 작동해 활성 앱의 포커스를 빼앗지 않으며, 기본 기능 사용 시 화면 녹화나 그리기 권한이 필요 없다.

주요 기능 및 통합

이 도구는 설치 가능한 스킬을 통해 Claude Code와 Codex와 연동된다. 에이전트는 bigarrow point로 임시 표시를 그리거나 bigarrow start로 지속 표시를 실행할 수 있다. 주요 기능은 다음과 같다:

• 타겟팅: 좌표(--at X,Y), 창 제목(--window App:title), 접근성 요소(--element Label --app App)를 지원한다.
• 시각적 옵션: 곡선, 직선, 지그재그, 나선형 등 다양한 모양과 화살표, 링, 상자 스타일, 색상 및 크기를 맞춤 설정할 수 있다.
• 자동화: 이동하는 요소를 추적하는 --follow, 상호작용 시 사라지는 --until-click, 음성 안내를 위한 --say 기능을 제공한다.
• 에이전트 인식: 소유 에이전트 프로세스가 종료되거나 bigarrow stop --hook 같은 훅을 통해 화살표를 자동으로 제거한다.

기술 구현 및 제한 사항

bigarrow는 AI 도구가 아닌 결정론적 CLI 유틸리티다. Core Animation을 사용해 렌더링하며, 펄스화 화살표 기준 1.4% CPU로 낮은 리소스를 사용한다. 멀티 디스플레이, Stage Manager, Spaces 환경을 지원한다.

• 권한: 기본 그리기는 별도 권한이 필요 없다. 단, 접근성 요소 타겟팅(--element)은 bigarrow가 아닌 셸(Terminal, VS Code 등)에 접근성 권한이 있어야 한다.
• 브라우저 지원: Electron 앱과 호환된다. Chrome에서 --element를 사용하려면 --force-renderer-accessibility 옵션으로 실행하거나 VoiceOver를 활성화해야 한다.
• 범위: 지시 및 주석 전용이다. 클릭, 타이핑, 화면 캡처는 수행할 수 없다.

개발 및 검증

기존 주석 도구 26종 조사 결과, 에이전트를 위한 프로그래밍 방식의 종료 코드 기반 지시 도구가 부재하여 개발되었다. 지오메트리, 창 서버 상호작용, 접근성 픽스처를 포함한 87개의 자동 테스트를 거쳤으며 macOS 15, 26, 27에서 검증됐다. MIT 라이선스로 배포되며 Homebrew(brew install franzenzenhofer/tap/bigarrow)로 설치할 수 있다.