화면에 큰 화살표가 표시되는 기능
big-arrow-on-the-screen이라고도 불리는 bigarrow는 모든 창 위에 눈에 잘 띄는 화살표와 안내문을 표시하는 macOS 명령줄 도구입니다. 대부분의 컴퓨터 작업을 수행할 수 있지만 특정 결정을 사람에게 다시 맡겨야 하는 AI 에이전트를 위해 설계되었습니다.
예를 들어 에이전트는 시스템 설정의 허용 버튼을 가리키거나, 올바른 브라우저 창을 식별하거나, 여러 단계로 이루어진 작업 흐름을 안내할 수 있습니다. 사용자가 계속 제어권을 갖습니다. bigarrow는 절대 클릭하거나 입력하거나 화면을 캡처하지 않습니다.
오버레이는 일반 창, 대화상자, 전체 화면 앱, Spaces 위에 표시되며, 키보드 포커스는 기존에 포커스를 가진 애플리케이션에 그대로 유지됩니다. 대상 위치를 클릭하면 아래 애플리케이션으로 클릭이 전달됩니다. 또한 지정된 시간이 만료되거나 소유 프로세스가 종료되면 화살표가 자동으로 사라집니다.
에이전트가 해야 할 일을 설명한 다음, 사람이 사용해야 할 정확한 컨트롤에 눈에 보이는 손가락을 올려둘 수 있습니다.
사용 시점
AI 에이전트가 사람에게 결정을 내리거나 작업을 완료하도록 요청해야 할 때마다 bigarrow를 유용하게 사용할 수 있습니다. 일반적인 예로 권한 요청, OAuth 동의 화면, 2단계 인증, CAPTCHA, 패스키, 결제, 서명, 법적 확인이 있습니다.
비슷한 창이나 컨트롤이 여러 개 표시되어 있을 때 지시를 더 명확하게 만들 수도 있습니다. 에이전트는 사용자가 열려 있는 여러 창을 직접 찾아보도록 요청하는 대신 특정 애플리케이션, 창 또는 브라우저 탭을 선택할 수 있습니다.
그 밖에도 애플리케이션 사용법을 가르치거나, 원격 지원을 제공하거나, 화면 녹화 중 컨트롤을 강조하거나, 다른 자동화 도구가 반환한 좌표가 올바른지 확인하는 데 사용할 수 있습니다.
macOS에 설치
이 프로젝트는 macOS 14 이상을 지원합니다. 가장 간단한 설치 방법은 Homebrew입니다.
brew install franzenzenhofer/tap/bigarrow
Claude Code와 Codex가 이 도구를 언제 어떻게 사용해야 하는지 알게 하려면 에이전트 스킬도 설치하세요.
bigarrow install-skill이 명령은 Claude Code용 스킬을 ~/.claude/skills에, Codex용 스킬을 ~/.agents/skills에 설치합니다. 스킬을 설치하지 않고 셸에서 bigarrow를 직접 호출할 수도 있습니다.
소스에서 빌드
프로젝트를 직접 컴파일하려면 Xcode 16 이상을 사용하세요.
swift build -c release생성된 바이너리는 .build/release/bigarrow에 있습니다. 애플리케이션 자체는 Swift로 작성되었습니다. scripts/의 셸 및 Python 파일은 스크린샷과 테스트에 사용됩니다.
첫 번째 가리키기 명령
기본적인 사용 패턴은 접근성 요소를 가리키는 방법, 좌표를 가리키는 방법, 중지할 때까지 화살표를 표시하는 방법의 세 가지입니다.
레이블이 있는 컨트롤 가리키기
bigarrow point --element "Allow" --app "System Settings" --text "Franz, click Allow: Ghostty may control your Mac"--element는 레이블로 컨트롤을 찾고, --app은 해당 컨트롤이 포함된 애플리케이션을 지정합니다. 안내문은 사용자에게 무엇을 해야 하는지 설명합니다.
좌표 가리키기
bigarrow point --at 760,500 --text "Franz, click HERE"좌표는 전역 기준 왼쪽 상단 논리 포인트를 사용합니다. macOS 접근성 API, CGWindowList, Peekaboo가 보고하는 좌표 공간과 동일합니다. 사각형 영역을 가리킬 수도 있습니다.
bigarrow point --rect 600,400,240,80 --text "This is the area to review"다음 단계까지 화살표 표시하기
bigarrow start --window "Safari:Inbox" --text "This window"
bigarrow stopstart는 즉시 반환되고 화살표는 계속 표시됩니다. 현재 화살표를 제거하려면 stop을 사용하고, 모든 화살표를 제거하려면 stop --all을 사용하세요.
일회성 point 명령은 기본적으로 8초 동안 유지됩니다. --duration으로 이 시간을 변경할 수 있으며, start의 기본값은 300초입니다. 시간 제한 없이 사용하려면 --duration 0을 사용하세요.
올바른 대상 선택
bigarrow는 여러 대상 소스를 지원합니다.
--at X,Y는 좌표를 가리킵니다.--rect X,Y,W,H는 직사각형 영역을 강조 표시합니다.--mouse는 현재 마우스 위치를 가리킵니다.--window App[:title]은 창을 가리킵니다.--element Label --app App은 접근성 요소를 찾습니다.--peekaboo ID --snapshot see.json은 Peekaboo의see --json출력에 포함된 요소 ID를 사용합니다.
애플리케이션이 제공하는 컨트롤을 확인하려면 다음을 실행하세요.
bigarrow elements --app "System Settings"여러 디스플레이를 사용하는 경우 --display N을 지정하면 좌표와 사각형 값이 하나의 디스플레이를 기준으로 설정됩니다. 주 디스플레이의 왼쪽이나 위에 배치된 디스플레이에 대해서는 음수 전역 좌표도 지원됩니다.
올바른 창 또는 브라우저 탭 지정
--app App[:window or tab title] 또는 --window를 지정하면 bigarrow는 화살표를 그리기 전에 관련 애플리케이션, 창 또는 Chrome/Safari 탭을 앞으로 가져올 수 있습니다. 이렇게 하면 정확한 화살표가 엉뚱한 창 위에 표시되는 문제를 방지할 수 있습니다.
bigarrow point --app "Google Chrome:Pull request" --text "Review this pull request"사용자의 창을 현재 위치 그대로 두려면 --no-raise를 사용하세요. 나중에 다른 애플리케이션이 대상을 가리면 대상이 다시 보일 때까지 화살표가 숨겨집니다.
명확하고 유용한 화살표 만들기
화살표의 모양, 스타일, 크기, 모서리, 색상 및 동작을 사용자 지정할 수 있습니다.
--shape bend|straight|zigzag|spiral은 화살표 경로를 선택합니다.--style arrow|ring|box는 일반 화살표, 테두리만 있는 링 또는 테두리만 있는 상자를 선택합니다.--size S|M|L은 크기를 변경합니다.--corners round|sharp는 표지 모서리 모양을 제어합니다.--color red|orange|yellow|green|teal|blue|purple|pink|black|white|#RRGGBB는 기본 색상을 설정합니다.--border shadow|white-black|black은 테두리 효과를 변경합니다.--border-color,--text-color,--edge-color로 개별 색상을 사용자 지정할 수 있습니다.--close-button은 표지에 클릭 가능한 X를 추가합니다.
예를 들어 다음 명령은 대상 주위에 눈에 잘 띄는 녹색 상자를 그립니다.
bigarrow point --at 760,500 --style box --color green --text "Review this control"닫기 버튼은 선택 사항이며, 사람이 오버레이를 직접 닫을 수 있는 방법을 제공합니다.
bigarrow start --element "Save" --app "TextEdit" --close-button --text "Click Save when ready"
유용한 상호작용 옵션
여러 옵션을 사용하면 오버레이를 안내 워크플로에 연결할 수 있습니다.
--follow는 창이나 요소를 따라 화살표를 이동합니다.--until-click은 대상을 클릭하면 화살표를 종료합니다.--say는 표지의 내용을 소리 내어 읽어 줍니다. 사용자가 화면을 보고 있지 않을 수 있을 때 유용합니다.--json은 에이전트와 스크립트에서 사용할 수 있는 기계 판독용 출력을 제공합니다.
따라서 안내 시퀀스는 한 컨트롤을 가리키고 사용자의 동작을 기다린 후 화살표를 멈추고 다음 컨트롤을 가리킬 수 있습니다. 이 도구가 클릭을 직접 수행하지는 않습니다.
권한 이해하기
오버레이를 그리는 데 macOS 화면 기록 또는 손쉬운 사용 권한은 필요하지 않습니다. 그러나 대상을 찾거나 활성화하는 일부 방식에는 권한이 필요합니다.
--at,--rect,--mouse,--window App,--peekaboo,--app App에는 권한이 필요하지 않습니다.--element,elements,--until-click,--app App:title에는 손쉬운 사용 권한이 필요합니다.--window App:title은 창 제목을 읽기 위해 화면 기록 권한이, 창을 앞으로 가져오기 위해 손쉬운 사용 권한이 필요합니다. 단,--no-raise를 사용하면 창을 앞으로 가져오는 권한은 필요하지 않습니다.
macOS는 이러한 권한을 bigarrow 바이너리 자체가 아니라 bigarrow를 실행한 애플리케이션(예: Terminal, iTerm2, Ghostty, VS Code 또는 Claude)에 부여합니다.
관련 권한, 해당 권한을 소유한 애플리케이션 및 연결된 디스플레이를 확인하려면 진단 명령을 실행하세요.
bigarrow doctor필요한 권한이 없으면 명령은 상태 코드 4로 종료되고 관련 애플리케이션과 설정 패널을 표시합니다.
자동 정리를 안전하게 사용하기
에이전트가 작업을 마친 후에도 화살표가 남아 있지 않도록 설계되었습니다. 시간이 지정된 point 명령은 자동으로 사라집니다. 또한 화살표를 만든 에이전트 프로세스가 종료되면 화살표도 종료됩니다. 이때 사용 가능한 경우 CLAUDE_PID 또는 BIGARROW_OWNER_PID를 사용합니다.
Claude Code 워크플로에서는 bigarrow stop --hook을 UserPromptSubmit 훅으로 사용하여 사용자가 응답할 때 해당 세션의 화살표를 지울 수 있습니다. 명시적인 정리 명령은 다음과 같습니다.
bigarrow stop
bigarrow stop --all이러한 안전장치는 에이전트가 정상적인 정리 단계에 도달하기 전에 중단되거나 교체될 수 있는 경우에 유용합니다.
에이전트 워크플로에서 JSON과 종료 코드 사용하기
모든 명령은 --json을 지원하므로 결과를 프로그래밍 방식으로 확인하기가 더 쉽습니다. 문서에 정의된 종료 코드는 다음과 같습니다.
0: 명령이 성공적으로 완료되었습니다.2: 입력이 올바르지 않습니다.3: 대상을 찾을 수 없습니다.4: 필요한 권한이 없습니다.
에이전트는 이러한 결과를 바탕으로 다른 대상 지정 방법으로 재시도할지, 사용자에게 권한을 요청할지, 또는 요청한 컨트롤을 찾을 수 없다고 설명할지를 결정할 수 있습니다.
고급 대상 디버깅
손쉬운 사용, Peekaboo 또는 다른 도구에서 가져온 좌표가 올바른지 확신할 수 없다면 드라이 런을 사용하세요.
bigarrow point --at 760,500 --dry-run --json
이 명령은 오버레이를 그리지 않고 도구가 가리킬 위치를 보고합니다. 사용자에게 무언가를 표시하기 전에 좌표 변환, 디스플레이 선택 및 자동화 결과를 검증할 때 유용합니다.
Peekaboo를 다른 대상 소스로 사용할 수도 있습니다. Peekaboo JSON 스냅샷을 캡처한 다음 일치하는 요소 ID를 전달하세요.
bigarrow point --peekaboo ELEMENT_ID --snapshot see.json --text "Review this element"Chrome에서는 페이지 요소에 Chrome의 --force-renderer-accessibility 플래그나 VoiceOver가 필요할 수 있습니다. Chrome 자체 툴바는 일반적인 접근성 경로를 통해 계속 사용할 수 있습니다. 페이지 콘텐츠가 노출되지 않으면 대신 좌표를 사용하세요.
에이전트가 이 스킬을 사용하는 방법
포함된 스킬은 하나의 Agent Skills 호환 SKILL.md를 통해 Claude Code와 Codex를 모두 지원하며, Codex 메타데이터는 agents/openai.yaml에 있습니다. 이 스킬은 에이전트에게 언제 가리켜야 하는지, 대상을 선택하는 방법, 표지판에 완전한 문장을 작성하는 방법, 언제 --say를 사용해야 하는지, 사용자가 행동한 후 언제 중지해야 하는지를 알려 줍니다.
실용적인 에이전트 순서는 다음과 같습니다.
- 사람의 확인이나 도움이 필요한 작업을 식별합니다.
- 레이블, 창, 탭, 좌표, 사각형 또는 Peekaboo 대상을 선택합니다.
- 사용자가 무엇을 해야 하는지와 그 이유를 정확히 설명하는 표지판을 작성합니다.
- 현재 레이아웃을 유지하는 것이 중요하지 않다면 대상 애플리케이션을 앞으로 가져옵니다.
- 사람이 행동하거나 응답할 때까지 기다립니다.
- 다음 단계로 진행하기 전에 화살표를 중지합니다.
이 도구가 하지 않는 일
bigarrow는 의도적으로 기능을 제한했습니다. 사람을 위한 화면 주석 도구, 클릭 봇 또는 스크린샷 도구가 아닙니다. 화면을 클릭하거나, 입력하거나, 캡처하지 않습니다. 이 도구의 목적은 프로그램의 지시를 눈에 보이게 하면서 결정과 행동은 사람에게 맡기는 것입니다.
링과 상자 스타일은 윤곽선을 사용하므로 대상이 계속 보입니다. 공간이 있으면 표지판은 대상에서 떨어진 곳에 배치되며, 닫기 버튼이 활성화된 경우 사람은 이를 통해 화살표를 닫을 수 있습니다. 이러한 설계 선택 덕분에 이 도구는 권한, 인증, 결제 및 배포와 같은 민감한 작업에 적합합니다.
결론
bigarrow는 macOS 기반 AI 에이전트가 모호한 터미널 메시지에 의존하지 않고 간단한 방식으로 제어권을 사람에게 돌려줄 수 있게 합니다. Homebrew로 설치하고, 필요한 경우 Claude Code 또는 Codex 스킬을 추가한 다음, 짧은 프롬프트에는 point를, 안내형 워크플로에는 start와 stop을 사용하세요.
레이블, 창, 좌표, 사각형, 마우스 및 Peekaboo 대상과 사용자 지정 스타일, 음성, JSON 출력, 자동 정리 및 다중 디스플레이를 지원하는 이 도구는 “여기를 클릭해 주세요”를 정확한 화면 안내로 바꾸면서 최종 작업은 사람이 직접 제어하도록 합니다.