New to Claude Skills? Learn how to install them →

Get Claude Skills
openclaw on GitHub

Peekaboo

Free

Automate macOS UI tasks with a powerful CLI.

by openclaw385.8k stars on openclaw/openclaw
Updated Aug 10, 2026
Get this skill

Free · Opens the source repo

What Peekaboo does

Peekaboo is a command-line interface (CLI) tool designed for automating tasks within the macOS user interface. It allows developers and designers to capture and inspect screens, interact with UI elements, and manage applications, windows, and menus programmatically. This skill is particularly useful for those looking to streamline repetitive tasks or integrate UI automation into their workflows. With a variety of commands, users can perform actions like capturing screenshots, simulating mouse clicks, typing text, and managing app states, all from the terminal.

The tool operates by utilizing the OpenClaw macOS application, which facilitates communication between the CLI and the system's accessibility features. Users must ensure they have the necessary Screen Recording and Accessibility permissions enabled for Peekaboo to function correctly. The CLI commands are designed to be intuitive, with options for JSON output to facilitate scripting and automation. For example, users can capture images of specific UI elements, execute scripts defined in JSON format, or even manage multiple applications and windows seamlessly.

Peekaboo is ideal for developers who want to automate testing processes, designers who need to create UI prototypes quickly, or anyone who frequently interacts with the macOS interface. The ability to script complex workflows through simple command-line instructions can significantly enhance productivity and reduce the time spent on manual tasks. Additionally, the built-in tools for inspecting UI elements and managing application states provide a comprehensive solution for macOS automation needs.

In summary, Peekaboo offers a robust CLI for macOS UI automation that caters to a wide range of users. Its focus on accessibility and ease of use makes it a valuable addition to any developer or designer's toolkit, enabling them to automate and optimize their interactions with the macOS environment.

When to use it

Use Peekaboo when you need to automate interactions with macOS applications or manage UI elements programmatically.

When not to use it

This tool is not suitable for users who prefer GUI-based automation tools or those without programming experience.

What you can build with it

Automating Testing Workflows

Developers can use Peekaboo to automate UI testing by scripting interactions with applications, ensuring consistent test execution.

Creating UI Prototypes

Designers can leverage Peekaboo to quickly prototype UI interactions by simulating user actions through the command line.

Managing Application States

Users can automate the management of application windows and states, such as launching, quitting, or focusing on specific apps.

How to install Peekaboo

View source

1. Install with the skills CLI

npx skills add openclaw/openclaw/peekaboo --agent claude-code

2. Or install it manually

Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.

Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs

Inside SKILL.md

Written by openclaw

Peekaboo

Peekaboo is a full macOS UI automation CLI: capture/inspect screens, target UI elements, drive input, and manage apps/windows/menus. Commands share a snapshot cache and support --json/-j for scripting. Run peekaboo or peekaboo <cmd> --help for flags; peekaboo --version prints build metadata. Tip: run via polter peekaboo to ensure fresh builds.

OpenClaw Bridge

The OpenClaw macOS app hosts Peekaboo Bridge at ~/Library/Application Support/OpenClaw/bridge.sock. Before running Peekaboo from OpenClaw, select that socket so the CLI uses the app's Screen Recording and Accessibility grants instead of starting its standalone daemon:

export PEEKABOO_BRIDGE_SOCKET="${PEEKABOO_BRIDGE_SOCKET:-$HOME/Library/Application Support/OpenClaw/bridge.sock}"

Confirm routing with peekaboo bridge status --json; hostKind must be gui and the socket path must end in OpenClaw/bridge.sock.

Features (all CLI capabilities, excluding agent/MCP)

Core

  • bridge: inspect Peekaboo Bridge host connectivity
  • capture: live capture or video ingest + frame extraction
  • clean: prune snapshot cache and temp files
  • config: init/show/edit/validate, providers, models, credentials
  • image: capture screenshots (screen/window/menu bar regions)
  • learn: print the full agent guide + tool catalog
  • list: apps, windows, screens, menubar, permissions
  • permissions: check Screen Recording/Accessibility status
  • run: execute .peekaboo.json scripts
  • sleep: pause execution for a duration
  • tools: list available tools with filtering/display options

Interaction

  • click: target by ID/query/coords with smart waits
  • drag: drag & drop across elements/coords/Dock
  • hotkey: modifier combos like cmd,shift,t
  • move: cursor positioning with optional smoothing
  • paste: set clipboard -> paste -> restore
  • press: special-key sequences with repeats
  • scroll: directional scrolling (targeted + smooth)
  • swipe: gesture-style drags between targets
  • type: text + control keys (--clear, delays)

System

  • app: launch/quit/relaunch/hide/unhide/switch/list apps
  • clipboard: read/write clipboard (text/images/files)
  • dialog: click/input/file/dismiss/list system dialogs
  • dock: launch/right-click/hide/show/list Dock items
  • menu: click/list application menus + menu extras
  • menubar: list/click status bar items
  • open: enhanced open with app targeting + JSON payloads
  • space: list/switch/move-window (Spaces)
  • visualizer: exercise Peekaboo visual feedback animations
  • window: close/minimize/maximize/move/resize/focus/list

Vision

  • see: annotated UI maps, snapshot IDs, optional analysis

Global runtime flags

  • --json/-j, --verbose/-v, --log-level <level>
  • --no-remote, --bridge-socket <path>

Quickstart (happy path)

peekaboo permissions
peekaboo list apps --json
peekaboo see --annotate --path /tmp/peekaboo-see.png
peekaboo click --on B1
peekaboo type "Hello" --return

Common targeting parameters (most interaction commands)

  • App/window: --app, --pid, --window-title, --window-id, --window-index
  • Snapshot targeting: --snapshot (ID from see; defaults to latest)
  • Element/coords: --on/--id (element ID), --coords x,y
  • Focus control: --no-auto-focus, --space-switch, --bring-to-current-space, --focus-timeout-seconds, --focus-retry-count

Common capture parameters

  • Output: --path, --format png|jpg, --retina
  • Targeting: --mode screen|window|frontmost, --screen-index, --window-title, --window-id
  • Analysis: --analyze "prompt", --annotate
  • Capture engine: --capture-engine auto|classic|cg|modern|sckit

Common motion/typing parameters

  • Timing: --duration (drag/swipe), --steps, --delay (type/scroll/press)
  • Human-ish movement: --profile human|linear, --wpm (typing)
  • Scroll: --direction up|down|left|right, --amount <ticks>, --smooth

Examples

See -> click -> type (most reliable flow)

peekaboo see --app Safari --window-title "Login" --annotate --path /tmp/see.png
peekaboo click --on B3 --app Safari
peekaboo type "user@example.com" --app Safari
peekaboo press tab --count 1 --app Safari
peekaboo type "supersecret" --app Safari --return

Target by window id

peekaboo list windows --app "Visual Studio Code" --json
peekaboo click --window-id 12345 --coords 120,160
peekaboo type "Hello from Peekaboo" --window-id 12345

Capture screenshots + analyze

peekaboo image --mode screen --screen-index 0 --retina --path /tmp/screen.png
peekaboo image --app Safari --window-title "Dashboard" --analyze "Summarize KPIs"
peekaboo see --mode screen --screen-index 0 --analyze "Summarize the dashboard"

Live capture (motion-aware)

peekaboo capture live --mode region --region 100,100,800,600 --duration 30 \
  --active-fps 8 --idle-fps 2 --highlight-changes --path /tmp/capture

App + window management

peekaboo app launch "Safari" --open https://example.com
peekaboo window focus --app Safari --window-title "Example"
peekaboo window set-bounds --app Safari --x 50 --y 50 --width 1200 --height 800
peekaboo app quit --app Safari

Menus, menubar, dock

peekaboo menu click --app Safari --item "New Window"
peekaboo menu click --app TextEdit --path "Format > Font > Show Fonts"
peekaboo menu click-extra --title "WiFi"
peekaboo dock launch Safari
peekaboo menubar list --json

Mouse + gesture input

peekaboo move 500,300 --smooth
peekaboo drag --from B1 --to T2
peekaboo swipe --from-coords 100,500 --to-coords 100,200 --duration 800
peekaboo scroll --direction down --amount 6 --smooth

Keyboard input

peekaboo hotkey --keys "cmd,shift,t"
peekaboo press escape
peekaboo type "Line 1\nLine 2" --delay 10

Notes

  • Requires Screen Recording + Accessibility permissions.
  • In OpenClaw subprocesses, set PEEKABOO_BRIDGE_SOCKET as shown above. Do not pass --no-remote unless the calling process has its own Screen Recording grant.
  • Diagnose subprocess capture failures with peekaboo bridge status --json, then peekaboo permissions status --json, then a normal Bridge-routed capture such as peekaboo image --mode screen --json.
  • On macOS 15+, the "bypass private window picker" prompt is separate from the base Screen Recording grant; it can appear even when Bridge permissions are otherwise correct.
  • Use peekaboo see --annotate to identify targets before clicking.

Frequently asked questions about Peekaboo

Similar skills

Agent-Browser Core

Efficient browser automation for AI agents.

Setup My IQ

Effortlessly create and update your personal context portfolio.

CRM Maintenance

Automate HubSpot updates from your calendar and emails.

Zoom MCP

Streamline access to Zoom meeting assets and recordings.

Slack Automation

Automate tasks and extract data from Slack easily.

SMB Onboard

Guides small business owners through initial tool setup.