Community이미지github.com

steipete/peekaboo

macOS 스크린샷, UI 검사, 클릭, 타이핑, 앱/창 자동화

peekaboo란 무엇인가요?

Peekaboo는 macOS에서 화면 캡처, UI 요소 검사, GUI 자동화를 수행하는 강력한 CLI 도구입니다. 개발자와 AI 에이전트가 스크린샷을 찍고, 앱/창 목록을 확인하며, 특정 좌표를 클릭하거나 텍스트를 입력하는 등 마우스와 키보드 동작을 자동화할 수 있습니다. 또한 접근성(Accessibility) 및 화면 기록(Screen Recording) 권한을 확인하고 JSON 형식으로 결과를 반환하여 머신 파싱에 용이합니다. 주요 사용 사례로는 UI 테스트 자동화, 원격 Mac 제어, 앱 상태 모니터링 등이 있으며, Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 활용할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/steipete/agent-scripts/tree/main/skills/peekaboo

Installed? Explore more 이미지 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

peekaboo은(는) 무엇을 하나요?

macOS 화면 캡처, UI 검사 및 GUI 자동화에 사용합니다.

바이너리

  • ~/bin/peekaboo가 존재하면 우선 사용합니다. 이는 Peter의 로컬 릴리스 사본입니다.
  • 그렇지 않으면 peekaboo를 사용합니다.
  • 먼저 확인: ~/bin/peekaboo --version || peekaboo --version.

Mac 앱 호스트

  • 라이브 캡처/자동화 전에 Peekaboo.app을 실행하세요. CLI가 자동으로 실행하지 않습니다.
  • 앱이 TCC 권한을 소유하며 ~/Library/Application Support/Peekaboo/bridge.sock을 제공합니다.
  • 설치된 앱: open -a Peekaboo. 저장소 빌드: Apps/Mac/Peekaboo.xcodeproj의 Peekaboo 스킴을 빌드한 후 생성된 Peekaboo.app을 엽니다.
  • peekaboo daemon start는 앱 실행이 아닙니다. 데몬은 별도의 권한과 daemon.sock을 가집니다.
  • peekaboo bridge status --verbose --json에서 hostKind: gui를 선택했는지 확인하세요. 결정적인 앱 라우팅이 필요한 경우 --bridge-socket "$HOME/Library/Application Support/Peekaboo/bridge.sock"을 사용하세요.

안전

  • 캡처/자동화 전에 권한을 확인하세요: peekaboo permissions status --json.
  • 스크린샷에는 화면 기록(Screen Recording) 권한이 필요합니다. 클릭/타이핑/창 제어에는 접근성(Accessibility) 권한이 필요합니다.
  • 원격 Mac에서는 화면 기록이 없어 스크린샷이 차단될 수 있지만, 접근성 권한을 통해 클릭/타이핑은 여전히 작동합니다. 대상이 다른 방법으로 알 수 있는 경우 클릭이나 DOM 자동화로 계속 진행하세요.
  • 머신 파싱에는 --json을, 로컬 TCC 테스트 시에는 --no-remote를 선호합니다.
  • 사용자가 요청했거나 대상이 통제된 테스트 환경이 아닌 경우 클릭/타이핑/파괴적 자동화를 수행하지 마세요.

일반 명령어

PB="${PEEKABOO_BIN:-$HOME/bin/peekaboo}"
[ -x "$PB" ] || PB="$(command -v peekaboo)"

"$PB" permissions status --json
open -a Peekaboo
"$PB" bridge status --verbose --json
"$PB" list screens --json
"$PB" list apps --json
"$PB" list windows --app Safari --json
"$PB" image --mode screen --screen-index 0 --path /tmp/screen.png --json --no-remote
"$PB" see --app frontmost --path /tmp/frontmost.png --json --annotate
"$PB" tools --json
"$PB" learn
"$PB" click --coords 100,100 --json
"$PB" type "text" --json

워크플로우

  1. 위와 같이 PB를 확인하고 설치 상태가 중요한 경우 버전을 확인합니다.
  2. 라이브 UI 작업을 위해 Peekaboo.app을 실행합니다. GUI 브리지와 해당 권한을 확인합니다.
  3. permissions status --json을 실행합니다. TCC가 누락된 경우 정확히 누락된 권한을 보고합니다.
  4. 스크린샷의 경우 image를 사용합니다. --path, --json을 포함하고, 의도적으로 호출자 로컬 TCC를 테스트하는 경우에만 --no-remote를 사용합니다.
  5. 요소 타겟팅의 경우 see --json --annotate를 실행한 후 요소 ID/스냅샷으로 클릭합니다.
  6. 장기 실행/변경 감지 화면 캡처에는 capture live를, 비디오 프레임 샘플링에는 capture video를 사용합니다.
  7. 명령/도구 탐색에는 tools --json을, 전체 에이전트 가이드가 유용할 때는 learn을 사용합니다.
  8. sips -g pixelWidth -g pixelHeight <path>로 출력 파일을 확인하거나 이미지를 봅니다.

문서: ~/Projects/Peekaboo/docs/commands/.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

steipete/agent-transcript

GitHub PR/issue agent transcripts: redact, preview, and insert safely.

steipete/beeper

Beeper cache: contact hints, room lookup, WhatsApp/iMessage traces, FTS.

steipete/browser-use

Existing Chrome automation: Chrome plugin first, mcporter fallback.

steipete/clawsweeper-status

ClawSweeper status: URLs, workflow health, active workers, ops snapshot.

steipete/clickclack

ClickClack ops: chat app, Hetzner deploy, DNS/docs/app, Docker rollout.

steipete/cloudflare-registrar

Cloudflare Registrar: domain availability, prices, registration via mcporter.

steipete/codex-debugging

Codex debugging: codex-rs core/tui/exec/cli/app-server/config.

steipete/create-cli

CLI UX/spec: args, flags, help, output, errors, config, dry-run.

steipete/discord-clawd

Discord-backed OpenClaw agent/session relay; not archive search.

steipete/domain-dns-ops

DNS/domain ops: registrars, zones, redirects, DNS/HTTP verify, manager truth.

steipete/frontend-design

Frontend UI: pages, apps, components, polished non-generic design.

steipete/github-author-context

GitHub contributor context: identity, activity, trust, company/team signal.

steipete/github-cache-hygiene

GitHub quota/cache hygiene: gh, ghx, xcache, gitcrawl, mirrors, limits.

steipete/github-deep-review

GitHub deep review: bugs, PRs, best fix, stale-or-real, read code first.

steipete/github-project-triage

GitHub issue/PR triage: queues, CI, blockers, risk, proof, next actions.

steipete/hopper-debugger

Hopper debugging: macOS/iOS binaries, ObjC/Swift symbols, dyld, LLDB.

steipete/instruments-profiling

Instruments/xctrace profiling: macOS/iOS traces, binaries, args, exports.

steipete/mac-maintenance

Mac upkeep: brew update/upgrade, pull clean repos, empty Trash.

steipete/maintainer-orchestrator

Open-source maintainer orchestration: Codex app workers, work recovery, dependencies, vision, releases.

steipete/markdown-converter

Markdown conversion: PDF, Office, HTML, data, OCR, audio, ZIP, YouTube.

관련 스킬