AI 에이전트가 맥 화면 위에 직접 큰 화살표·박스·글자를 그려주는 도구, big-arrow 사용법
AI 에이전트가 복잡한 작업을 수행하다가 권한 허용창이나 특정 버튼 클릭이 필요할 때 터미널에 문자만 출력해 사용자가 놓치기 쉽습니다. big-arrow는 에이전트가 macOS 화면 위에 클릭 관통형 오버레이로 화살표, 박스, 텍스트를 직접 그려 사용자의 시선을 정확히 유도합니다. 이 글은 설치부터 Claude Code 연동, 실전 활용 예시까지 6단계로 정리합니다.
AI 에이전트가 리팩토링이나 마이그레이션 같은 복잡한 코드 작업은 척척 해내지만, 정작 '허용 버튼 눌러줘' 같은 단순 UI 조작 앞에서 터미널에 텍스트만 뱉고 멈춰 선 경험 있으신가요? big-arrow-on-the-screen은 에이전트가 맥 화면 전체에 투명한 오버레이를 띄워 화살표와 안내 문구를 직접 그려주는 오픈소스 CLI 도구입니다. 클릭은 그대로 통과하고 포커스도 뺏기지 않으며, 작업이 끝나면 저절로 사라집니다.
big-arrow란 무엇인가요
big-arrow는 macOS에서 실행되는 단일 CLI 도구이자 Claude Code·Codex 스킬로, AI 에이전트가 화면 위 모든 윈도우 위에 큰 화살표·박스·글자를 그려주는 유틸리티예요. 에이전트가 터미널에 "Allow 버튼 누르세요"라고만 출력하던 시절을 끝내고, 실제 버튼·탭·다이얼로그 위에 시각 마크를 띄워 사람이 바로 클릭하게 돕죠.
핵심 특징은 네 가지예요. 첫째 클릭 관통(click-through)이라 마크가 있어도 아래 버튼을 바로 누를 수 있고, 둘째 키보드 포커스 유지로 작업 흐름이 끊기지 않아요. 셋째 자동 제거 옵션으로 일정 시간 뒤 마크가 스스로 사라지며, 넷째 데몬·메뉴바 아이콘·계정·텔레메트리 없는 단일 Swift 바이너리라 설치 부담이 거의 없습니다. MIT 라이선스로 공개돼 누구나 자유롭게 쓸 수 있어요.
# Homebrew
brew install franzenzenhofer/tap/big-arrow
# 권한 부여 후 테스트
bigarrow start --element "Allow" --role button --app "System Settings" --from right --color green --close-button| 구분 | 내용 |
|---|---|
| 라이선스 | MIT |
| 바이너리 크기 | 약 2 MB (유니버설) |
| 필수 권한 | Accessibility (화면 제어) |
| 데몬 여부 | 없음 |
| 메뉴바 상주 | 없음 |
| AI 내장 여부 | 없음(순수 그리기 도구) |
자주 묻는 질문
Q: 화살표가 가려서 클릭 못 하면 어떡하죠? → A: 클릭 관통 모드라 화살표 위를 클릭해도 아래 버튼이 눌려요.
Q: 여러 모니터·스페이스에서도 동작하나요? → A: 네, 모든 디스플레이·스페이스 위에 단일 투명 윈도우로 그려집니다.
Q: 백그라운드 데몬이 떠 있나요? → A: 전혀 없습니다. 실행 즉시 그리고 옵션에 따라 스스로 종료돼요.
- 권한 프롬프트(OAuth, 2FA, 패스키) 버튼 가리키기
- 코드 리뷰 중 특정 줄·파일 하이라이트
- 부모님·원격 동료 화면 공유 시 "이 버튼 누르세요" 안내
- 키노트·블렌더 등 복잡한 앱 단계별 튜토리얼 마크
왜 이 도구가 필요한가요
AI 에이전트가 코드 리팩토링, 마이그레이션 작성, 복잡한 개념 설명까지 척척 해내도 시스템 권한 프롬프트·2FA·캡차·결제 버튼 같은 UI 요소 앞에서는 멈춥니다. 보안 정책상 에이전트가 직접 클릭할 수 없거나, 사용자 확인이 꼭 필요한 단계이기 때문입니다. 기존에는 터미널에 "Allow 버튼을 누르세요" 같은 텍스트만 남겨두는데, 사용자가 그 창을 보고 있지 않으면 놓치기 일쑤입니다.
big-arrow는 이 지점에서 에이전트가 화면 위 모든 윈도우 위에 투명한 오버레이 창을 띄워 큰 화살표·박스·글자·링·지그재그 등 다양한 마커를 그려줍니다. 클릭 이벤트는 그대로 통과(click-through)하고 키보드 포커스도 유지되며, 작업이 끝나면 저절로 사라집니다. 별도 데몬·메뉴바 아이콘·계정·텔레메트리 없이 단일 Swift 바이너리 하나로 동작합니다.
| 상황 | 기존 방식 | big-arrow 활용 |
|---|---|---|
| 시스템 권한 허용 | 터미널에 텍스트 안내 | 초록 화살표 + 'Franz, click Allow' 문구로 버튼 정확 위치 지정 |
| 2FA·캡차·패스키 | 사용자가 직접 찾음 | 에이전트가 PIN·코드를 화면에 크게 표시, 복사 버튼까지 제공 |
| 복잡한 앱 메뉴(Keynote, Finder, Chrome 탭) | 말로 설명 | 역할·앱·요소명으로 대상 특정 후 스타일·위치·크기 옵션으로 즉시 하이라이트 |
| 원격 지원·가족 도움 | 화면 공유 중 구두 안내 | 화살표가 실시간으로 가리키니 '위쪽 두 번째 버튼' 같은 모호함 제거 |
에이전트가 '사람을 불러오는' 세 가지 패턴
- 권한·동의·결제 등 에이전트가 누르면 안 되는 버튼을 사람이 누르도록 유도
- 2FA·캡차·패스키·서명 등 사람만 할 수 있는 인증 단계에서 코드·URL·명령어를 화면에 크게 표시
- 블렌더·키노트 등 학습이 필요한 UI를 단계별로 포인트하며 가이드
bigarrow start --element Terminal_Toggle --app "Ghostty" --from right --color green --close-button설치 및 권한 설정 3단계
brew install franzenzenhofer/tap/big-arrow설치 뒤 bigarrow version으로 버전이 찍히는지 확인하세요. 이제 권한 두 가지를 열어야 에이전트가 화면 전체에 오버레이를 그릴 수 있습니다.
1. 손쉬운 사용(Accessibility) 허용
시스템 설정 → 개인정보 보호 및 보안 → 손쉬운 사용에서
bigarrow(또는 터미널/에디터)를 토글 켬. 목록에 없으면 '+' 버튼으로/usr/local/bin/bigarrow또는 사용하는 셸을 직접 추가하세요.2. 화면 녹화(Screen Recording) 허용
같은 화면의 '화면 녹화' 항목에서도 동일하게
bigarrow/터미널/에디터를 켜줍니다. 권한 변경 후에는 해당 앱(터미널, VS Code, Cursor 등)을 완전히 껐다 켜야 적용됩니다.3. 빠른 진입용 단축 URL(선택)
시스템 설정 깊이 들어가지 않으려면 터미널에서 아래 명령으로 바로 해당 패널을 열 수 있어요.
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"| 항목 | 필수 여부 | 비고 |
|---|---|---|
| 손쉬운 사용(Accessibility) | 필수 | 오버레이 윈도우 생성·제어용 |
| 화면 녹화(Screen Recording) | 필수 | 전체 화면·모든 스페이스에 그리기 위해 필요 |
| Full Disk Access | 불필요 | big-arrow는 파일 시스템 접근 안 함 |
여기까지 마쳤다면 에이전트가 bigarrow start … 명령을 보낼 때마다 화면 위에 화살표·박스·글자가 바로 나타납니다. 다음 섹션에서는 실제 에이전트(Claude Code·Codex)와 연동해 자연어로 "저 버튼 눌러줘"라고 말하면 화살표가 따라붙게 하는 법을 다룹니다.
Claude Code·Codex 스킬 등록 및 기본 명령어
설치와 권한 설정을 마쳤다면 이제 Claude Code·Codex 스킬을 등록해 에이전트가 bigarrow 명령을 바로 호출할 수 있게 합니다. 두 에이전트 모두 big-arrow-on-the-screen 저장소에 포함된 스킬 파일을 읽어오면 별도 설정 없이 --element, --app, --role 같은 주요 옵션을 바로 쓸 수 있습니다.
Claude Code에 스킬 추가하기
스킬 파일 복사
저장소 루트의
skills/claude-code/big-arrow.md파일을 프로젝트나 전역.claude/skills/폴더에 넣으세요.에이전트 재시작
Claude Code를 다시 열면
bigarrow스킬이 자동 로드됩니다.동작 확인
채팅창에 "bigarrow start --element Test --app Finder --from top --color red"라고 입력해 화살표가 뜨는지 확인하세요.
Codex에 스킬 추가하기
스킬 파일 복사
skills/codex/big-arrow.md를 Codex 스킬 디렉터리(~/.codex/skills/또는 프로젝트.codex/skills/)에 넣으세요.Codex 재시작
Codex를 다시 실행하면 스킬이 활성화됩니다.
테스트
동일하게
bigarrow start --element Demo --app Safari --from bottom --style ring --color blue를 실행해 보세요.
bigarrow start 핵심 옵션 한눈에 보기
| 옵션 | 설명 | 예시 |
|---|---|---|
| --element | 강조할 UI 요소 이름 (Accessibility 트리 기준) | Terminal_Toggle, Add, PDF, Cancel |
| --app | 대상 애플리케이션 번들 식별자 또는 표시 이름 | Ghostty, Keynote, TextEdit, Finder |
| --role | 요소의 접근성 역할 (button, radiobutton, menubutton 등) | button, radiobutton, menubutton |
| --from | 화살표가 어디서 날아올지 방향 | top, bottom, left, right, top-left, bottom-right |
| --style | 오버레이 스타일 | arrow(기본), box, ring |
| --color | 화살표·박스·링 색상 | red, green, blue, orange, pink, teal, black, yellow |
| --shape | 화살표 머리 모양 | straight(기본), zigzag |
| --size | 크기 프리셋 | S, M(기본), L |
| --text | 표지판에 표시할 안내 문구 | "Mom, click PDF, then Save as PDF" |
| --close-button | 표지판에 닫기 버튼 표시 여부 | 플래그만 주면 활성화 |
| --border-color / --text-color | 박스·링 테두리·글자 색상 별도 지정 | --border-color white-black --text-color yellow |
위 옵션을 조합하면 "Ghostty의 Terminal_Toggle 버튼을 오른쪽에서 녹색 화살표로 가리키기"(bigarrow start --element Terminal_Toggle --app Ghostty --from right --color green) 같은 지시를 에이전트가 한 줄로 수행할 수 있습니다. --style ring --size S처럼 스타일·크기를 줄이면 미세한 포인터로, --style box --corners sharp --text "설명"이면 설명 박스로 쓸 수 있으니 용도에 맞춰 조합해 보세요.
주의할 점과 팁
실무에 도입하기 전 꼭 확인해야 할 체크리스트를 정리했어요. macOS 버전마다 권한 메뉴 위치가 다르고, 여러 대의 모니터나 스페이스를 쓸 때 오버레이가 어떻게 동작하는지 알면 나중에 헤매지 않습니다.
macOS 버전별 권한 경로 차이
다중 디스플레이·스페이스 대응
도구는 모든 디스플레이와 모든 스페이스 위에 투명 윈도우 한 장을 띄웁니다. 따라서 외부 모니터를 연결해도, Mission Control로 스페이스를 전환해도 화살표·박스·글자가 그대로 보입니다. 에이전트가 특정 앱 윈도우를 타깃으로 잡으면(--app "Ghostty" 등) 해당 윈도우가 어느 스페이스에 있든 자동으로 포커스를 맞춰 오버레이를 그립니다.
텍스트 내 {{변수}} 치환과 복사 버튼
--text 옵션에 {{482913}}처럼 이중 중괄호로 감싼 값이 있으면, 오버레이 표지판에 복사 버튼이 생깁니다. 사용자가 버튼을 누르면 중괄호 안 숫자·문자열만 클립보드에 들어갑니다. PIN, 임시 비밀번호, 원타임 코드 등을 에이전트가 화면에 띄워주면서 '복사해서 붙여넣기'까지 한 번에 유도할 때 유용해요.
bigarrow start --element PIN --app Safari --role button \
--text "Franz, copy & paste the PIN {{482913}} here" \
--from bottom --color pink --border white-blackTTS 음성 안내 옵션
자료에 따르면 표지판 텍스트를 macOS 내장 TTS로 읽어주는 기능이 있습니다. 에이전트가 "I need you, and you're making coffee." 같은 문장을 넣으면 맥이 소리 내어 불러줘서, 사용자가 다른 방에 있거나 화면을 보지 않을 때도 알림을 받을 수 있어요. 별도 데몬 없이 say 명령어를 내부에서 호출하는 방식이라 추가 설치가 필요 없습니다.
MIT 라이선스 무료 활용 범위
- 소스 코드·바이너리 상업적 이용·수정·재배포 자유
- 별도 허가 없이 사내 자동화 스크립트·제품 임베드 가능
- 라이선스 원문(LICENSE 파일)만 배포물에 포함하면 의무 완료
- 특허 보복 조항·보증 없음·면책 조항 표준 적용