peekaboo

What This Skill Does

Peekaboo is a robust macOS UI automation framework that provides deep, programmatic access to the operating system's graphical user interface. By bridging the gap between high-level agent logic and low-level accessibility APIs, it allows users to inspect, interact with, and automate virtually any application running on macOS. It operates through a specialized CLI that enables precise control over mouse movements, keyboard input, application window management, and system-level dialogs. Whether you need to scrape data from a legacy application, orchestrate a complex cross-app workflow, or perform visual quality assurance on UI components, Peekaboo offers a unified interface for these tasks.

Installation

To integrate Peekaboo into your OpenClaw environment, use the provided clawhub installation command. Ensure you have the necessary macOS accessibility permissions granted for your terminal environment:

clawhub install openclaw/openclaw/skills/peekaboo

After installation, run peekaboo permissions to verify that your system is correctly configured to allow UI automation. Using the wrapper polter peekaboo is recommended to ensure you are operating with the latest build and environment configurations.

Use Cases

Peekaboo excels in scenarios where traditional API-based automation is impossible or incomplete. Common use cases include:

• Automating legacy desktop applications that lack an exportable data format.
• Creating regression tests that verify UI layout, menu responsiveness, and component visibility.
• Cross-application data migration where information must be copied from one window to another.
• Automated form completion in desktop GUI applications that do not support standard CLI inputs.
• System-level orchestration, such as managing Spaces, organizing windows, or monitoring the menu bar for status changes.

Example Prompts

1. "Peekaboo, take a look at the open browser window, find the 'Export' button, click it, and then save the resulting file to my Desktop."
2. "List all active windows in the current workspace, then focus on the Slack application and send a message saying 'Busy, back soon' by typing it and pressing enter."
3. "Using Peekaboo, monitor the system menu bar for the VPN status icon; if it disappears, click the app icon in the Dock to relaunch the client."

Tips & Limitations

• Targeting: Always use unique element IDs (--id) when possible. If IDs are missing, fallback to specific coordinates or window title filtering.
• Permissions: Peekaboo requires Accessibility permissions. If commands fail silently, check System Settings > Privacy & Security > Accessibility.
• Performance: Use the --json flag for all script-based tasks to ensure machine-readable outputs and consistent performance. Avoid heavy visual polling in production scripts; instead, rely on explicit waits where feasible.
• Safety: Because this tool has full control over your input devices, avoid running scripts from untrusted sources in high-privilege windows.