Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Peekaboo는 macOS 환경에서 화면 캡처, 접근성 검사, 네이티브 UI 자동화를 지원하는 CLI 및 메뉴 바 앱입니다. 이 도구는 개발자가 직접 사용하거나, AI 에이전트가 다단계 작업을 계획하고 실행할 수 있도록 하는 강력한 자동화 기능을 제공합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Codex tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기CI npm GitHub release macOS 15+ Swift 6.2 Node License Homebrew Ask DeepWiki
Peekaboo는 화면 캡처, 접근성 검사(accessibility inspection), 네이티브 UI 자동화를 위한 macOS CLI 및 메뉴 바 앱입니다. 이를 직접 사용하거나, 에이전트가 다단계 작업을 계획하도록 하거나, 동일한 도구 세트를 MCP 클라이언트에게 노출할 수 있습니다.
Peekaboo banner
릴리스된 CLI와 앱은 macOS 15 이상을 요구합니다.
brew install openclaw/tap/peekaboo
npm 패키지는 Node.js 22 이상을 요구하며, CLI와 그 MCP 런처가 포함되어 있습니다.
npx -y @steipete/peekaboo --version
Codex, Claude Code, Cursor 또는 다른 MCP 클라이언트에 연결하려면 MCP 설정을 참조하십시오.
최신 GitHub 릴리스에서 서명된 DMG를 다운로드하십시오. 메뉴 바 앱은 권한 온보딩, 시각적 피드백, 에이전트 세션을 제공합니다. 또한 PATH에 peekaboo가 필요한 경우 CLI를 별도로 설치해야 합니다.
소스 빌드 및 대체 설치 세부 정보는 설치 가이드를 참조하십시오.
Peekaboo에 사용 가능한 권한을 확인한 다음, 스크린샷을 찍어보십시오:
peekaboo permissions status
peekaboo see --no-elements --mode screen --path /tmp/peekaboo-screen.png
화면 캡처에는 화면 녹화 권한(Screen Recording permission)이 필요합니다. 접근성 권한(Accessibility permission)은 UI 검사 및 제어를 활성화하며, 권한 가이드에서 설정과 합성 입력(synthetic input)에 사용되는 추가 권한을 다룹니다.
실행 중인 앱을 검사하여 불투명 요소 ID가 포함된 구조화된 UI 맵을 얻으십시오:
peekaboo see --app Finder --json
이것이 핵심 루프입니다. 현재 화면을 관찰하고, 결과에서 요소를 선택한 다음, 그 요소에 대해 행동합니다.
Peekaboo 4.9.6은 수정(fix) 릴리스입니다. Xcode의 Device Hub처럼 실행 시 스스로 재실행하는 앱들은 더 이상 보이지 않지 않습니다: AppKit은 해당 앱의 PID를 -1로 보고하며, Peekaboo는 이제 확인된 활성 프로세스 하나를 복구하여 목록에 표시하고 검사하며 캡처할 수 있게 했습니다. window close는 앱이 닫힌 창을 살아있게 유지하거나 종료될 때 성공을 보고하며, Mac 앱의 저장된 Vision 모델은 이미지 분석에 사용되고, Mac 채팅은 후속 대화에서도 Stop을 연결 상태로 유지하며, 모든 프롬프트와 답변을 한 번씩 기록하고, 메뉴 바를 동기화 상태로 유지하며, 클릭한 최근 세션을 열어줍니다.
Safari의 창 목록을 가져온 다음, 의도하는 window_id(12345 아래)를 복사하고, 전체 상호작용을 정확히 그 창에 고정합니다:
peekaboo window list --app Safari --json
peekaboo click "주소 및 검색창" --app Safari --window-id 12345
peekaboo type "github.com/openclaw/Peekaboo" --app Safari --window-id 12345
...
대상화된 의미론적(semantic) 및 유형 지정형(typed) CLI 입력은 Peekaboo가 프로세스를 해결할 수 있을 때 백그라운드 전송을 사용하므로, 앱이 포그라운드로 올 필요가 없습니다. 원시 CLI press 코드는 정확한 창 선택기를 사용하여 백그라운드 상태를 유지할 수도 있습니다. 또한 CLI는 새로운 정확한 비대화형(non-dialog) 스냅샷도 허용합니다. 이 스냅샷은 백그라운드 전용 Agent/MCP 정책에 필요합니다.
앱/PID 전용 및 대상 없는(targetless) 코드는 명시적인 포그라운드 동의를 요구하며, 창 선택기만 사용하는 Agent/MCP 코드도 마찬가지입니다.
가능하다면 menu click과 같은 의미론적 동작을 선호하세요. 요소 ID, 좌표, 스냅샷, 대기 시간(waits), 입력 동작에 대한 내용은 자동화 가이드를 참조하세요.
Agent는 동일한 관찰 및 행동 도구를 자연어 실행으로 결합합니다:
peekaboo agent "Safari를 열고, github.com으로 이동하여 Peekaboo를 검색해 줘" --allow-foreground
Agent를 실행하려면 설정된 모델 제공업체(configured model provider)가 필요합니다. 제공업체 및 세션에 대한 정보는 agent setup를 참조하거나, Peekaboo의 도구를 다른 클라이언트에서 노출하려면 MCP setup를 참고하세요.
| 목표 (Goal) | 명령어 (Commands) | 가이드 (Guide) |
|---|---|---|
| 데스크톱 관찰 (Observe the desktop) | see, screen list, window list | 캡처 및 검사 |
| ... | ||
Run peekaboo help <command>를 사용하여 실시간 CLI 도움말을 확인하세요. 전체 명령어 인덱스 (complete command index)에는 모든 명령어에 대한 플래그, 예시 및 문제 해결 정보가 연결되어 있습니다. |
Peekaboo는 제공업체 자격 증명(provider credentials)과 설정을 ~/.peekaboo 아래에 저장합니다. peekaboo config를 사용하여 이를 검사하거나 변경할 수 있으며, 프로필, 환경 변수 및 사용자 지정 제공업체에 대한 자세한 내용은 설정 가이드 (configuration guide)를 참고하세요. 제공업체 참조 (provider reference)에는 호스팅형(hosted), 호환형(compatible), 로컬 모델 백엔드가 포함되어 있습니다.
zsh, bash, fish용 셸 완성 기능(Shell completions)은 peekaboo completions에서 가져옵니다. 지속적인 설정을 위해서는 완성 기능 가이드 (completion guide)를 확인하세요.
소스 빌드를 위해서는 macOS 15 이상, Swift 6.2 이상, Node.js 22 이상 및 저장소의 서브모듈이 필요합니다.
pnpm install --frozen-lockfile
pnpm run build:cli
pnpm run lint:docs
...
더 많은 빌드(build), 서명(signing), 테스트 세부 정보는 docs/building.md에서 확인할 수 있습니다.
MIT. 자세한 내용은 LICENSE를 참고하세요.