Community图像github.com

steipete/peekaboo

macOS 屏幕截图、UI 检查、点击、输入和窗口/应用自动化工具。

peekaboo 是什么?

Peekaboo 是一款专为 macOS 设计的 GUI 自动化工具,支持屏幕截图、UI 检查、点击、键盘输入及窗口/应用控制。它通过 CLI 和本地运行的 Peekaboo.app 配合工作——CLI 本身不会自动启动应用,因此使用前需先通过 `open -a Peekaboo` 启动应用,以确保 TCC(透明度、同意与控制)权限正确授予。工具会优先查找 `~/bin/peekaboo` 作为二进制路径,否则回退到系统 PATH 中的 `peekaboo`。在执行任何截屏或自动化操作前,应通过 `peekaboo permissions status --json` 检查权限:屏幕录制权限用于截图,辅助功能权限用于点击、输入和窗口控制。在远程 Mac 上,可能缺少屏幕录制权限但辅助功能仍可工作,此时可继续使用点击或 DOM 自动化。Peekaboo 适用于 Claude Code 等 AI 代理平台,提供丰富的命令集(如截图、元素定位、实时捕获、视频采样等)和 `learn` 命令以便获取完整指南。

兼容平台~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 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 scheme,然后打开生成的 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。
  • 截图需要屏幕录制权限;点击/输入/窗口控制需要辅助功能权限。
  • 在远程 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.

相关技能