bigarrow CLI: macOS AI 에이전트를 위한 시각적 가이드

TL;DR – bigarrow의 기능과 중요성

bigarrow는 macOS용 단일 바이너리 명령줄 도구로, 모든 창이나 화면 좌표 위에 클릭 가능한 화살표, 상자, 선택적 텍스트를 그리고 자동으로 사라집니다. 그리기 작업에 화면 녹화나 접근성 권한이 필요하지 않으며, 다중 디스플레이, Spaces, 전체 화면 앱에서 작동합니다. 또한 AI 에이전트가 성공 또는 실패를 안정적으로 알릴 수 있도록 정확한 종료 코드를 반환합니다. 에이전트에게 클릭 대신 가리키는 방법을 제공함으로써, bigarrow는 많은 자동화 워크플로우에서 인간만이 수행할 수 있었던 마지막 단계를 연결합니다.

핵심 기능 – 에이전트에게 필요한 세 가지 명령어

결론: 에이전트는 화살표를 가리키고, 추적하고, 제거하기 위한 세 가지 간단한 명령어만 있으면 됩니다.

명령어	목적	예시
`bigarrow point`	UI 요소(라벨 기준) 또는 화면 좌표에 화살표를 그리고, 선택적으로 캡션을 추가합니다.	`bigarrow point --element "Allow" --app "System Settings" --text "Franz, click Allow"`
`bigarrow start` / `bigarrow stop`	에이전트가 명시적으로 중지하거나 타임아웃이 만료될 때까지 화살표를 표시합니다.	`bigarrow start --window "Safari:Inbox" --text "This window" && bigarrow stop`
`bigarrow point --at X,Y`	라벨 기반 타겟팅을 사용할 수 없는 경우(예: 접근성이 없는 웹 페이지) 원시 좌표를 타겟팅합니다.	`bigarrow point --at 760,500 --text "Franz, click HERE"`

모든 명령어는 --duration, --json 출력 및 전체 스타일링 플래그(모양, 색상, 크기 등)를 지원합니다. 종료 코드는 결정론적입니다: 0 성공, 2 잘못된 입력, 3 타겟을 찾을 수 없음, 4 권한 부족.

왜 클릭이 아닌 가리키기인가?

결론: 가리키기는 사용자의 주체성을 존중하고 보안 위험을 피하면서도 인간을 안내합니다.

권한 대화 상자 – macOS 프롬프트(예: “Allow”)를 에이전트가 직접 클릭하지 않고도 강조 표시할 수 있습니다.
민감한 작업 – 2FA, CAPTCHA, 결제 확인, 법적 체크박스는 인간의 통제하에 유지됩니다.
창 구분 – 여러 Chrome 창이 열려 있을 때 --window "Google Chrome:Pull request"는 올바른 탭을 선택한 후 가리킵니다.
오디오 신호 – --say는 캡션을 소리 내어 읽어주어 사용자의 주의를 환기합니다.
원격 지원 – “다른 톱니바퀴 아이콘”이라고 설명하는 대신 에이전트가 직접 가리킬 수 있습니다.
문서화 – --png는 화살표를 PNG로 렌더링하여 정적 문서나 스크린캐스트에 활용할 수 있습니다.
디버깅 – --dry-run --json은 그리지 않고 계산된 타겟을 보고하므로 좌표 확인에 유용합니다.

이 도구는 의도적으로 클릭, 타이핑, 스크린샷 캡처를 하지 않으며, 순수한 시각적 신호 역할만 합니다.

설치 및 통합

결론: bigarrow는 Homebrew를 통해 설치하거나 소스에서 빌드할 수 있으며, Claude Code / Codex 스킬이 포함되어 있습니다.

brew install franzenzenhofer/tap/bigarrow
bigarrow install-skill   # Claude Code (~/.claude/skills) 및 Codex (~/.agents/skills)용 스킬 등록

소스 빌드: swift build -c release (Xcode 16+, macOS 14+ 필요). 결과 바이너리는 .build/release/bigarrow에 위치합니다.

스타일링 옵션 – 화살표를 눈에 띄게 만들기

결론: 풍부한 시각적 매개변수 세트를 통해 어떤 배경에서도 화살표가 눈에 띄도록 합니다.

모양: bend, straight, zigzag (긴급), spiral (한 번 회전).
스타일: arrow (기본값), ring, box (테두리만).
크기: S, M, L.
모서리: round 또는 sharp.
색상: 이름 지정된 팔레트(red, orange, …) 또는 사용자 지정 #RRGGBB.
테두리: shadow (기본값), white-black, black.
닫기 버튼: --close-button은 클릭 시 화살표를 제거하는 X 표시를 추가합니다.
동적 동작: --follow는 움직이는 창을 추적하고, --until-click은 클릭 시 종료되며, --say는 음성 합성을 트리거합니다.

이 프로젝트에는 모든 조합을 화면 밖에서 렌더링하고 화살표가 표지판과 만나는 지점을 확대하여 매끄러운 시각적 외관을 보장하는 갤러리 스크립트가 포함되어 있습니다.

권한 모델 – 왜 화면 녹화가 필요 없는가?

결론: 그리기는 macOS가 추가 권한 없이 허용하는 투명 오버레이 창을 사용하며, 타겟 발견 기능에만 접근성이 필요합니다.

그리기 – 화면 녹화나 접근성 권한이 필요하지 않습니다.
타겟 조회 – --element, elements, --until-click, --window는 접근성에 의존하며, macOS는 이를 bigarrow 자체가 아닌 셸 프로세스(Terminal, iTerm, VS Code, Claude)에 부여합니다.
bigarrow doctor – 필요한 권한을 가진 앱을 보고하고, 권한이 없으면 코드 4로 종료합니다.

이 설계는 도구가 화면 콘텐츠를 몰래 캡처하는 것을 방지하면서도 정확한 UI 요소 식별을 가능하게 합니다.

macOS 환경 전반의 견고성

결론: 화살표는 다중 디스플레이, 전체 화면 앱, Stage Manager, Spaces에서 작동하며 디스플레이 연결 해제 시에도 적절하게 대응합니다.

기본 화면의 왼쪽/위에 있는 디스플레이에 대한 음수 좌표를 지원합니다.
화살표가 있는 상태에서 디스플레이 연결을 해제하면 화살표가 정중하게 사라집니다.
CI를 통해 macOS 15, 26, 27에서 검증되었습니다.
CPU 영향은 최소화되어 CI 러너에서 약 1.4%이며, Core Animation이 렌더링을 처리합니다.

저자가 강조한 실제 사용 사례

결론: bigarrow는 AI 보조 워크플로우의 구체적인 문제점을 해결합니다.

권한 프롬프트 – 에이전트가 누를 수 없는 “Allow” 클릭 대화 상자.
2FA / CAPTCHA – 에이전트가 가리키고, 인간이 확인합니다.
창 선택 – 수십 개의 Chrome 창 중에서 구분합니다.
안내 온보딩 – 시작/중지 의미론을 사용한 단계별 투어.
원격 도움말 – 동료에게 올바른 UI 요소를 가리킵니다.
문서화 – 주석이 달린 스크린샷을 자동으로 생성합니다.
좌표 디버깅 – 접근성 또는 Peekaboo 좌표의 시각적 확인.

커뮤니티 피드백 – 주요 의견 요약

결론: 사용자는 개념을 높이 평가하지만 안전성, 사용성 및 더 넓은 적용 가능성에 대해 우려를 제기합니다.

"‘화면 녹화나 접근성이 필요한가?’ 부분을 읽으려 했지만 내용이 부실했습니다… ‘거절’ 버튼을 가리는 상자를 그리는 것을 무엇이 막나요?" – @hn8726 (그리기는 UI 요소를 절대 차단하지 않으며, 표지판 자체만 클릭 가능하다는 점을 명확히 함.)

"화살표는 ‘어디를 클릭할지’는 해결하지만 ‘클릭해야 하는지’는 해결하지 못합니다. 인간의 의사결정 역할을 줄일 수 있습니다." – @tilemarch (윤리적 경계를 강조함; 도구는 의도적으로 클릭 자동화 직전에서 멈춤.)

"전화로 엄마가 문서를 다운로드하고 인쇄하도록 도울 때 정말 좋을 것 같습니다." – @arshxyz (보조 원격 지원을 위한 비 에이전트 사용 사례를 제안함.)

"올바른 앱을 실행하고 은행 송금 과정을 안내하는 iPad 버전에 돈을 지불할 의향이 있습니다." – @lbreakjai (크로스 플랫폼 UI 보조 도구에 대한 수요를 나타냄.)

"README가 기술적인 사람들을 대상으로 작성되었습니다; 더 간단한 UI가 채택을 넓힐 수 있을 것입니다." – @usrbinbash (문서 접근성을 지적함.)

전반적으로 커뮤니티는 시각적 안내의 가치를 인정하지만, 사용자 동의를 유지하기 위한 명확한 경계의 필요성을 강조합니다.

테스트 범위 및 신뢰성

결론: 광범위한 자동화 테스트가 기하학, 렌더링 및 상호작용 동작을 검증합니다.

기하학, 관절 부드러움, 골든 이미지 비교, 접근성 및 Peekaboo 픽스처와의 통합을 다루는 87개의 단위 테스트.
실제 macOS 윈도우 서버에서의 17개의 시각적 동작 검사: 클릭 통과, 포커스 유지, 다중 디스플레이 처리, CPU 사용량 등.
에이전트 스킬 테스트 – 새로운 Claude Code 에이전트가 스킬만을 사용하여 Chrome “새로고침” 버튼을 성공적으로 찾았으며, 회귀 테스트로 추가된 버그를 노출했습니다.

제한 사항 및 질문

결론: bigarrow는 일반적인 화면 주석 도구가 아니며 UI 자동화를 대체할 수 없습니다.

클릭, 타이핑, 스크린샷 캡처를 할 수 없습니다.
웹 페이지 요소 타겟팅은 --force-renderer-accessibility가 실행되거나 VoiceOver가 활성화된 경우에만 Electron 앱과 Chrome에서 작동합니다.
이 도구는 라벨 기반 타겟팅을 위해 접근성에 의존하며, 그렇지 않으면 좌표를 수동으로 제공해야 합니다.
아직 iOS/iPadOS 지원은 없으나 커뮤니티의 관심이 댓글을 통해 확인됩니다.

리포지토리에서 암시하는 향후 방향

결론: 저자는 문서를 확장하고, 스킬 형식을 개선하며, 추가적인 시각적 신호를 탐색할 계획입니다.

상세한 PLAN.md, DECISIONS/, RESEARCH/ 디렉토리가 아키텍처와 위험 평가를 개략적으로 설명합니다.
이전 작업으로는 Peekaboo 시각화 도구와 Nameplate가 있으며, bigarrow는 화살표와 라벨 오버레이의 격차를 메웁니다.
잠재적인 확장 기능에는 더 풍부한 애니메이션, 다중 에이전트 조정 또는 크로스 플랫폼 포팅이 포함될 수 있습니다.

결론

bigarrow는 AI 에이전트가 macOS의 UI 요소를 사용자에게 가리키도록 하는 가볍고 권한이 필요 없는 방법을 제공하여, 모호한 “이 버튼을 클릭하세요”라는 프롬프트를 사용자의 주체성과 시스템 보안을 유지하면서 명확한 시각적 신호로 바꿉니다. 최소한의 설치 공간, 강력한 테스트 및 유연한 스타일링은 에이전트 기반 워크플로우에 실용적인 추가 요소가 됩니다.