AI 에이전트가 화면에 큰 화살표, 상자 및 텍스트를 그리게 하세요

big-arrow-on-the-screen (bigarrow): 작은 macOS CLI와 에이전트 스킬로 구성되어 있습니다. 클릭 가능하며, 포커스를 절대 빼앗지 않고, 스스로 사라집니다. MIT.

License: MIT

AI 에이전트는 모노레포를 리팩토링하고, 마이그레이션을 작성하며, 모나드를 설명할 수 있지만, 단지 사용자가 버튼 하나를 클릭해야 할 때 터미널에 "대화 상자에서 Allow를 클릭해 주세요"라고 출력하는 경우가 있습니다. bigarrow가 이를 해결합니다.

bigarrow point --element "Allow" --app "System Settings" --text "Franz, click Allow"

크고 친근한 화살표와 표지판이 모든 것 위에 나타나서 특정 대상을 가리킨 후 다시 사라집니다. 클릭 가능하며, 포커스를 절대 빼앗지 않고, 모든 디스플레이와 모든 Space에서 작동하며, 그리는 데 어떠한 권한도 필요하지 않습니다. 이것은 작은 Swift 바이너리 하나입니다. 데몬도 없고, 메뉴 바 아이콘도 없고, 계정도 없고, 텔레메트리도 없으며, 저희가 두 번 확인했지만 AI도 없습니다. 그것은 화살표일 뿐입니다.

실제로 무엇을 위한 것인가요?

좋은 질문입니다. 화살표는 구석기 시대부터 존재해 왔습니다. 달라진 점은 다음과 같습니다: 소프트웨어 에이전트가 이제 Mac에서 실제 작업을 수행하며, 그들은 같은 벽에 계속 부딪힙니다. 오직 인간만이 할 수 있는 부분입니다.

• "Allow“을 클릭하세요." macOS 권한 프롬프트, OAuth 동의 화면, "...로 열기?" 대화 상자. 에이전트는 버튼을 찾을 수는 있지만, 대신 누르거나 누를 수 없습니다. 이제 그 버튼을 가리킬 수 있습니다.
• "당신의 차례입니다." 2FA 코드, CAPTCHA, 패스키(passkeys), 결제 확인, 서명, 법적 체크박스. 에이전트가 스스로의 이름으로 절대 클릭해서는 안 되는 것들입니다. 그것은 가리키고, 당신이 결정하고, 계속 진행합니다.
• "저 창이 아니라 이 창이에요." 크롬(Chrome) 창이 14개 있습니다. 에이전트는 어떤 것을 의미하는지 압니다: --window "Google Chrome:Pull request". 심지어 올바른 탭까지 선택합니다: --app "Google Chrome:Pull request".
• "제가 필요해요, 그런데 당신은 커피를 만들고 있네요." --say는 간판의 내용을 소리 내어 읽습니다. 당신의 Mac은 문자 그대로 당신을 책상으로 다시 불러낼 것입니다.
• 가이드 설정 및 온보딩. 사람에게 설정 창을 단계별로 안내합니다: start 실행, 사용자가 행동할 때까지 대기, stop 실행, 다음 단계 진행. 제품 투어와 비슷하지만 제품은 없습니다.
• 원격 지원. "아니요, 다른 톱니바퀴 아이콘이요." 설명하는 대신 그것을 가리킵니다.
• 데모, 화면 녹화, 문서. 녹화 중 중요한 부분을 강조하거나, --png를 사용하여 PNG 파일로 화살표를 바로 렌더링하여 문서를 만듭니다.
• 디버깅 좌표. 접근성(Accessibility), 스크린샷 또는 Peekaboo 좌표가 올바른지 확신이 서지 않나요? 그것들을 가리키고 확인하세요. --dry-run --json은 그릴 것 없이 어디를 가리킬 것인지 알려줍니다.

우리가 모두 겪어본 상황들

중립적인 데모 대화 상자로 꾸미고 실제 bigarrow로 깨끗한 CI 러너(BACKDROP_ARGS=--cover scripts/funny-scenes.sh)에서 녹화했습니다. 대화 상자는 가짜입니다. 감정은 진짜입니다.

Delete node_modules? Yes. Obviously.	Cookie banner: Franz, nobody reads these either
...
무엇이 아닌가: 사람을 위한 화면 주석 도구, 클릭 봇, 또는 스크린샷 도구. 그것은 절대 클릭하거나, 타이핑하거나, 무언가를 캡처하지 않습니다. 오직 가리킬 뿐입니다. 의도적으로.

설치

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에 위치합니다.

에이전트가 필요한 세 가지 명령어

bigarrow point --element "Allow" --app "System Settings" --text "Franz, click Allow"   # 레이블로 지정
bigarrow point --at 760,500 --text "Franz, click HERE"                                 # 좌표로 지정
bigarrow start --window "Safari:Inbox" --text "This window" && bigarrow stop            # 중지할 때까지 실행

모든 화살표는 스스로 종료됩니다. 에이전트가 잊어버린 경우에도 정리할 필요가 없습니다:

화살표는 자신이 가리키는 앱에 연결됩니다. --app App[:window or tab title] (또는 --window)을 사용하면 해당 앱, 창 또는 Chrome/Safari 탭이 먼저 전경으로 오게 됩니다. 이는 터미널 뒤에 숨겨진 창을 가리키는 것이 도움이 되지 않는 특별한 경우이기 때문입니다. 또한 다른 앱이 대상을 덮고 있어도 화살표가 숨었다가 다시 나타납니다. --no-raise를 사용하면 현재 창 배치를 그대로 유지합니다. bigarrow elements --app X는 --element로 매칭할 수 있는 항목 목록을 보여줍니다. bigarrow doctor는 권한, 소유자, 그리고 디스플레이 정보를 표시합니다.

모든 명령어는 --json을 사용합니다. 종료 코드는 다음과 같습니다: 0은 성공, 2는 잘못된 입력, 3은 대상 찾기 실패, 4는 권한 누락입니다. 에이전트는 종료 코드를 좋아하지만, 인간은 이를 참아냅니다.

모양(Looks)

화살표이기 때문에 그 모양에 엄청난 시간을 들였습니다.

깨끗한 테스트 장비에서 촬영한 실제 스크린샷으로, 흰색 배경, macOS 회색, 어두운 색, 검은색, 빨간색 그리고 복잡한 웹 페이지 등 여섯 가지 모양이 있습니다:

• --shape bend|straight|zigzag|spiral (zigzag는 정말로 긴급할 때; spiral는 가리키기 전에 표지판 주위를 한 바퀴 도는데, 놓칠 수 없게 만들어야 할 때)
• --style arrow|ring|box; 링(rings)과 박스(boxes)는 테두리만 있으므로 아래에 있는 내용이 여전히 보입니다.
• --size S|M|L, --corners round|sharp
• --color red|orange|yellow|green|teal|blue|purple|pink|black|white|#RRGGBB
• --border shadow|white-black|black: 기본값은 흰색 테두리(밝은 색상 위에서 어둡게 보임)와 드롭 섀도우입니다. white-black은 그림자 대신 흰색 테두리 밖에 얇은 검은색 가장자리를 만듭니다. black은 단순히 얇은 검은색 윤곽선일 뿐입니다.
• 모든 색상은 사용자의 것입니다: --border-color, --text-color, --edge-color, 그리고 X의 경우 --close-color와 --close-x-color. 생략하면 각각 읽기 쉬운 색상을 자체적으로 선택합니다.
• --close-button은 표지판의 오른쪽 끝에 X를 배치합니다(흰색 원, 화살표 색상의 X). 이 위치는 텍스트를 가리거나 화면을 벗어나게 하지 않습니다.
• --follow는 창이나 요소와 함께 움직이고, --until-click은 대상 클릭 시 종료하며, --say는 표지판의 내용을 말합니다.
• 여러 개의 화살표가 동시에 있어도 서로 간에 방해되지 않도록 합니다.

The 샤프트(shaft)는 둥근 모서리로 끝나지 않는 확장된 관절을 통해 표지판에서 나옵니다. scripts/gallery.py는 모든 조합을 화면 밖에 렌더링하고 모든 관절(junctions)로 확대합니다. 왜냐하면 관절의 이음매가 명백히 허용되지 않았기 때문입니다.

FAQ

화면 녹화(Screen Recording) 또는 접근성(Accessibility)이 필요한가요?
그리기 기능은 둘 다 필요하지 않습니다. --element, elements, --until-click 및 front --window는 접근성을 사용하며, 이는 macOS가 셸을 실행하는 앱(Terminal, iTerm2, Ghostty, VS Code, Claude)에 부여하고 bigarrow 자체에는 부여하지 않습니다. bigarrow doctor는 해당 앱의 이름을 알려주며, 종료 코드 4는 에이전트에게 무엇을 요청해야 하는지 정확히 알려줍니다. --window App:title은 창 제목을 읽으며, 이는 macOS가 화면 녹화 없이도 숨기지 않지만; --window App만 사용하는 것은 아무것도 필요하지 않습니다.

제가 타이핑하는 동안 제 집중력을 뺏을까요?
아닙니다. 그것이 프로젝트에서 가장 어려웠던 버그였습니다: NSApplication.run()은 터미널이 없는 프로세스를 조용히 활성화하기 때문에, 분리된 화살표들이 포커스를 가져갔습니다. bigarrow는 대신 자체적으로 이벤트를 펌핑하며, 테스트에서는 전경 앱이 절대 바뀌지 않음을 확인합니다.

화살표를 클릭해서 통과할 수 있나요?
네, 사인(sign)과 샤프트(shaft)를 제외한 모든 곳에서 가능합니다: 그곳을 클릭하면 화살표가 사라집니다 (포인터 아래에서 희미하게 어두워지며 그렇게 알려줍니다). 타겟을 클릭하거나 화살표 머리 근처 어느 곳을 클릭해도 앱으로 바로 이동합니다. 화살표를 클릭하는 것은 절대 포커스를 가져가지 않습니다.

여러 디스플레이? 전체 화면 앱? Stage Manager? Spaces?
네, 네, 네, 네. 메인 디스플레이의 왼쪽이나 위쪽(음수 좌표)도 포함됩니다. 화살표가 있는 상태에서 디스플레이를 분리해도 화살표는 예의 바르게 사라집니다. 검증 매트릭스를 확인하세요.

펄싱하는 화살표가 CPU에 얼마나 많은 비용을 지불하나요?
CI 러너에서 측정했을 때 1.4%입니다. Core Animation이 렌더 서버에서 작업을 수행합니다.

--element가 웹 페이지 내부에서도 작동하나요?
Electron 앱에서는 네, 작동합니다. Chrome의 경우, --force-renderer-accessibility로 실행하거나 (VoiceOver가 켜져 있는 경우)에만 작동합니다. Chrome은 일반적으로 페이지 콘텐츠를 노출해 달라는 요청을 무시하며, 이는 2026년 10월 Chrome에서 검증되었습니다. Chrome 자체 툴바는 항상 작동합니다. 그 외의 경우에는 페이지 좌표를 지정하면 되며, 이 스킬이 설명합니다.

그냥 [어떤 화면 주석 앱]을 사용하지 않나요?
그것들은 사람이 화면에 그림을 그릴 때 쓰는 것입니다. 이것은 셸(shell)에서 종료 코드와 함께 무언가를 가리키는 프로그램을 위한 것입니다. 한 줄을 쓰기 전에 스물여섯 개의 도구를 확인했습니다(연구). 아무것도 이런 기능을 하지 못했습니다.

이것이 AI인가요?
아닙니다. 이것은 여러분의 AI 스택에서 가장 지능적이지 않은 부분이며, 그것을 자랑스럽게 생각합니다.

작동 원리 설명

• 87개의 자동화 테스트: 기하학, 배치, 관절 부드러움, 골든 이미지, 기록된 window-server, 접근성 및 Peekaboo 4.9.0 Fixtures, 그리고 실제 window server에 대한 테스트(window 레벨 1000, 클릭 통과, 포커스 이동 없음, 분리 및 중지 타이밍). CI는 이를 macOS 15에서 실행하며, macOS 26 및 macOS 27에서도 통과했습니다.
• 깨끗한 러너(visual.yml)에서의 17가지 동작 검사: X에서의 실제 클릭, --until-click, --follow, 올리기(및 --no-raise), 가려질 때 숨기기, Chrome 탭 선택, 소유 프로세스로 끝내기, stop --hook, --say, 전체 화면 앱, Stage Manager, Space 전환, 두 번째 디스플레이, 2배율 디스플레이, 화살표 도중 디스플레이 분리, CPU. 위의 데모 GIF는 아무것도 개인적으로 없는 데스크톱에서 동일한 워크플로우로 기록되었습니다.
• 스킬만 부여받고

Peekaboo의 visualizer (https://github.com/openclaw/Peekaboo)와 Peter Steinberger가 만든 Nameplate (https://github.com/steipete/Nameplate)는 오버레이 창 레시피와 에이전트-스킬 패키징을 보여주었습니다. 하지만 둘 다 라벨이 붙은 포인팅 화살표를 그리지는 못하며, 이것이 본 프로젝트가 채우는 공백입니다. bigarrow는 Peekaboo의 see --json을 선택적 목표 소스로 읽습니다.

라이선스

MIT. 책임감 있게 사용하세요.