AI 에이전트가 화면에 화살표·텍스트를 그리는 macOS CLI 5단계
AI 에이전트가 버튼을 클릭하거나 입력을 요구할 때, 화면에 어디를 눌러야 할지 알려줄 방법이 없습니다. 기존 방법은 텍스트만으로 안내해 혼란을 초래하고, 에이전트는 UI 요소를 직접 조작하지 못합니다. 이 자료는 macOS 전용 CLI ‘big‑arrow‑on‑the‑screen’를 설치하고, AI 에이전트가 화면에 화살표·박스·텍스트를 그려 사용자와 소통하도록 설정하는 방법을 단계별로 안내합니다.
‘big‑arrow‑on‑the‑screen’은 AI 에이전트가 macOS 화면 위에 투명한 오버레이를 그려, 사용자가 필요한 조작을 쉽게 찾도록 돕는 도구입니다. 한 줄 명령으로 시작하고, 클릭은 그대로 전달되며, 자동으로 사라지는 간편한 워크플로를 제공합니다.
이 도구가 무엇인가요
big‑arrow‑on‑the‑screen은 macOS 전용 CLI와 Claude Code·Codex용 스킬을 하나로 묶은 무료 도구예요. 터미널에서 한 줄 명령만 입력하면 현재 화면 위에 투명한 창을 띄워 화살표·상자·텍스트를 그려 줍니다. 클릭은 그대로 통과하고 키보드 포커스는 변하지 않으며, 표시가 끝나면 자동으로 사라져요. MIT 라이선스로 배포되며, 백그라운드 데몬, 메뉴바 아이콘, 계정·텔레메트리·AI 엔진이 전혀 없는 순수 Swift 바이너리입니다.
bigarrow start --element Terminal_Toggle --app1️⃣ 권한 설정
시스템 환경설정 → 보안 및 개인정보 보호 → 접근성에서 도구에 접근 허용을 클릭합니다.
2️⃣ 터미널 열기
macOS 기본 터미널을 실행하고
bigarrow명령이 있는 경로로 이동합니다.3️⃣ 요소 지정
bigarrow start --element <요소명> --app <앱이름>형태로 표시하고 싶은 요소와 대상 앱을 지정합니다.4️⃣ 스타일 선택
--color,--shape,--size옵션으로 색상·모양·크기를 조정합니다. 예:--color green --shape zigzag --size S5️⃣ 확인 및 자동 사라짐
화면에 화살표·텍스트가 나타나면 원하는 동작을 수행하고, 도구는 자동으로 창을 닫아 깔끔하게 정리됩니다.
| 특징 | 설명 |
|---|---|
| 투명 창 | 모든 디스플레이와 Space 위에 겹쳐 표시 |
| 클릭‑통과 | 화살표 위에 마우스를 올려도 클릭이 원래 창으로 전달 |
| 자동 삭제 | 표시가 끝나면 스스로 사라짐 |
| 라이선스 | MIT |
화면에 화살표가 안 보일 때는?
먼저 접근성 권한이 제대로 설정됐는지 확인하고, 명령에 --from 옵션으로 정확한 위치를 지정했는지 점검해 보세요. 그래도 안 나오면 터미널에 오류 메시지가 표시되는지 확인하고, 최신 버전으로 업데이트합니다.
- button
- radiobutton
- menubutton
- box
- ring
- zigzag
요약하자면, big‑arrow‑on‑the‑screen은 복잡한 UI 안내를 텍스트와 그래픽으로 시각화해 주는 간단한 macOS CLI 도구예요. 별도의 백그라운드 서비스 없이 즉시 실행되고, Claude Code·Codex와 연계하면 AI 에이전트가 사용자에게 필요한 클릭을 정확히 가리키도록 도와줍니다. 개발자든 일반 사용자든 화면 안내가 필요할 때 손쉽게 활용해 보세요.
왜 사용해야 하나요
AI 에이전트가 코드를 고치고 문서를 쓰고 테스트까지 돌려도, "이 버튼을 눌러주세요"라는 말만 터미널에 남겨두면 사람은 그 창을 보고 있지 않아서 놓치기 일쑤예요. big‑arrow‑on‑the‑screen은 에이전트가 화면 맨 앞 투명 레이어에 화살표·박스·텍스트를 그려서, 클릭 이벤트는 그대로 통과시키고 포커스도 뺏지 않으며, 일이 끝나면 저절로 사라지게 해 이 간극을 메워요.
어떤 장면에서 빛을 발하나요
- 권한 프롬프트·OAuth 동의·"다음으로 열기" 다이얼로그: 에이전트가 버튼을 찾아 화살표로 가리킴
- 2FA·CAPTCHA·패스키·전자서명·결제: 사람이 직접 판단·실행 후 에이전트가 이어받음
- PIN·URL·명령어 등 텍스트 전달: 표지판에 복사 버튼을 달아 원클립보드 전송
- 원격 지원·화면 공유: "위쪽 버튼, 아니 그 옆" 같은 모호한 말 대신 직관적 포인팅
- 튜토리얼·제품 투어: 블렌더·키노트 등 앱에서 단계별 컨트롤 하이라이트
데몬·메뉴바 아이콘·계정·텔레메트리 없이 단일 Swift 바이너리로 동작하고, MIT 라이선스라 부담 없이 도입할 수 있어요. 다음 섹션에서는 실제 설치·권한 부여·첫 화살표 실행을 5단계로 정리해 보여드릴게요.
설치·사용 단계
big‑arrow‑on‑the‑screen을 사용하려면 먼저 macOS용 실행 파일을 확보해야 합니다. 공식 GitHub 저장소에서 최신 릴리스를 다운로드하면 Swift로 컴파일된 단일 바이너리를 얻을 수 있습니다. 별도의 데몬이나 메뉴바 아이콘이 없으니 파일을 원하는 위치(예: /usr/local/bin)로 복사하고 실행 권한을 부여하면 준비가 끝납니다.
1. 바이너리 다운로드
GitHub Release 페이지에서 macOS용 bigarrow 바이너리를 다운로드합니다.
2. 파일 이동 및 권한 부여
터미널에서
chmod +x bigarrow로 실행 권한을 주고,sudo mv bigarrow /usr/local/bin/로 시스템 경로에 옮깁니다.3. 접근성 권한 설정
시스템 설정 → 보안 및 개인정보 보호 → 접근성에서 “bigarrow”에 체크하여 화면에 그릴 수 있는 권한을 허용합니다. 직접 열려면
x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility주소를 사용합니다.4. 기본 명령어 실행
권한이 적용됐으면 터미널에서 원하는 요소를 지정해 실행합니다.
bigarrow start --element Terminal_Toggle --app위 명령은 현재 포커스가 있는 터미널 창 위에 클릭을 가로채지 않는 투명 화살표와 “Terminal_Toggle” 라는 텍스트를 표시합니다. 옵션을 바꾸면 색상·위치·모양을 자유롭게 조정할 수 있어, 예를 들어 --from right --color green --close-button 은 오른쪽에 초록색 화살표와 닫기 버튼을 추가합니다.
--from <위치>: 화면 상의 시작점 (top, bottom‑right 등)--color <색상>: 화살표 색상 지정--style <스타일>: ring, box 등 모양 선택--size <S|M|L>: 크기 지정
한눈에 보기
big-arrow-on-the-screen은 화살표·박스·링·지그재그 같은 도형 스타일, 출발 방향, 색상, 크기, 텍스트까지 한 줄 명령으로 조합해 화면 위에 띄웁니다. 클릭은 통과하고 포커스는 그대로 유지되며, 설정한 시간이나 닫기 버튼으로 스스로 사라집니다.
| 옵션 | 설명 | 예시 값 |
|---|---|---|
| --element | 대상 UI 요소 이름 (Accessibility 식별자) | Terminal_Toggle, Add, Animate, Play, PDF, Cancel, Group |
| --role | 요소 역할 (버튼·라디오버튼·메뉴버튼 등) | button, radiobutton, menubutton |
| --app | 대상 애플리케이션 번들 이름 | Terminal, Keynote, TextEdit, Finder, Ghostty |
| --from | 화살표가 시작되는 방향 | right, bottom-right, top, top-left, bottom |
| --style | 도형 스타일 | arrow(기본), ring, box, zigzag |
| --color | 도형·선 색상 | green, orange, teal, pink, black, blue |
| --size | 크기 프리셋 | S, M(기본), L |
| --corners | 박스 모서리 모양 (style=box일 때) | sharp, round |
| --text | 함께 표시할 안내 문구 (줄바꿈 \\n 가능) | "3. Press play. Bask in the applause." |
| --close-button | 닫기 버튼 표시 여부 | 플래그만 주면 활성화 |
| --border / --border-color | 테두리 색상(단색 또는 그라데이션) | white-black, yellow |
| --text-color | 텍스트 색상 | yellow |
자주 쓰는 조합 예시
# 시스템 설정 → 접근성 권한 창의 토글 버튼
bigarrow start --element Terminal_Toggle --app Ghostty --from right --color green --close-button
# Keynote 재생 버튼에 지그재그 화살표 + 안내 텍스트
bigarrow start --element Play --app Keynote --role button --text "3. Press play. Bask in the applause." --from top --color teal --shape zigzag --size S
# TextEdit 프린트 다이얼로그 ‘PDF → Save as PDF’ 버튼
bigarrow start --element PDF --role button --app TextEdit --text "Mom, click PDF, then Save as PDF" --from bottom --color pink --border white-black
# Finder 보기 메뉴의 그리드 아이콘(라디오버튼) 강조
bigarrow start --element Group --role menubutton --app Finder --text "No, the other grid icon. This one." --from top --style box --color green
# PIN 코드 복사 버튼 역할 텍스트(자동 복사 기능 포함)
bigarrow start --text "Franz, copy & paste the PIN {{482913}} here" --color blue --border-color yellow --text-color yellow주의할 점
이 도구는 화면 최상단에 투명 창을 띄워 도형을 그리므로 macOS 접근성 권한이 반드시 필요합니다. 권한이 없으면 아무것도 그려지지 않고 종료 코드만 남으니, 첫 실행 전 시스템 설정 → 개인정보 보호 및 보안 → 손쉬운 사용에서 bigarrow(또는 터미널 앱) 토글을 켜두세요. 권한 창을 바로 열고 싶다면 터미널에서 open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility" 명령어를 실행하면 됩니다.
다중 디스플레이·스페이스 환경
자료에 따르면 모든 디스플레이와 모든 스페이스 위에 단일 투명 창이 생성됩니다. 따라서 외부 모니터를 쓰거나 Mission Control로 데스크톱을 전환해도 화살표는 화면 좌표 기준으로 정확히 나타납니다. 다만 각 모니터의 해상도·배율 차이가 클 때 요소 좌표 계산이 의도와 어긋날 수 있으니, --from 방향 옵션(예: --from right, --from top-left)으로 상대 위치를 지정해 보완하세요.
보안·샌드박스 제약
단일 Swift 바이너리로 배포되며 데몬, 메뉴바 아이콘, 계정, 텔레메트리, 내부 AI 없음을 명시하고 있습니다. 코드 서명된 바이너리만 실행하므로 Gatekeeper 경고가 뜰 수 있는데, xattr -d com.apple.quarantine bigarrow로 격리 속성을 제거하거나 우클릭 → 열기로 1회 허용하면 됩니다. 시스템 무결성 보호(SIP)가 활성화된 상태에서도 접근성 권한만 있으면 정상 동작합니다.
xattr -d com.apple.quarantine bigarrow자주 놓치는 체크리스트
- 손쉬운 사용 권한을 터미널 앱(Ghostty, iTerm2, Terminal 등) 또는
bigarrow바이너리 자체에 부여했는가? - 외부 모니터 연결 시 해상도·배율 설정이 의도한 좌표와 일치하는가?
- Gatekeeper 격리 속성 때문에 실행이 차단되지 않았는가?
--app옵션으로 정확한 애플리케이션 번들 식별자(Bundle ID)를 넘겼는가?
정리
big‑arrow‑on‑the‑screen은 macOS 전용 단일 바이너리 CLI와 Claude Code·Codex용 스킬로 구성된 무료(MIT) 도구입니다. 화면 최상단에 투명 창을 띄워 화살표·박스·링·지그재그 같은 도형과 텍스트를 클릭 통과(click‑through) 상태로 그려주고, 작업이 끝나면 자동으로 사라집니다. 별도 데몬·메뉴바 아이콘·계정·텔레메트리가 없고, AI 로직도 내부에 없으므로 가볍고 안전하게 쓸 수 있어요.
핵심 기능 한눈에 보기
| 항목 | 내용 |
|---|---|
| 지원 도형 | arrow(기본) · box · ring · zigzag |
| 출발 방향 | top · bottom · left · right · top-left · top-right · bottom-left · bottom-right |
| 색상·크기 | --color, --size(S/M/L), --border-color, --text-color 등 자유 지정 |
| 텍스트·복사 | --text "내용" → 사인에 표시, {{코드}} 형태면 복사 버튼 자동 생성 |
| 자동 종료 | --close-button 플래그로 닫기 버튼 추가, 타임아웃 없이 사용자 액션까지 유지 |
| 접근성 | macOS 접근성 권한 필수(시스템 설정 → 보안 및 개인정보 보호 → 접근성) |
| 멀티 디스플레이/스페이스 | 모든 디스플레이·스페이스에 동시 오버레이 가능 |
| 통합 스킬 | Claude Code / Codex용 스킬 기본 제공(에이전트가 한 줄 명령으로 호출) |
빠른 시작 체크리스트
참고 리소스
- GitHub 저장소: https://github.com/franzenzenhofer/big-arrow-on-the-screen (MIT 라이선스, 이슈·PR 환영)
- 6페이지 PDF 가이드(스크린샷 전부 에이전트가 그린 화살표) — 저장소 내
guide.pdf참조 - 접근성 권한 딥링크:
x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility