peekaboo

What This Skill Does

Peekaboo is a powerful, comprehensive CLI-based automation engine designed specifically for the macOS ecosystem. It provides a robust interface for interacting with the operating system at the UI layer, effectively acting as an invisible hand that can inspect, navigate, and manipulate desktop applications. Unlike simple macro recorders, Peekaboo leverages deep system integration to identify UI elements, manage window states, and orchestrate complex workflows across multiple applications. It is built to be scriptable, offering JSON output for every command, which makes it an ideal tool for complex agentic workflows where decision-making must be informed by real-time visual and structural data from the macOS desktop.

Installation

To add the Peekaboo skill to your environment, use the OpenClaw hub CLI. Execute the following command in your terminal: clawhub install openclaw/skills/skills/steipete/peekaboo. Once installed, it is highly recommended to run the tool via polter peekaboo to ensure you are always interacting with a fresh, stable build. Before running complex automations, verify your environment settings by running peekaboo permissions to ensure the tool has necessary Accessibility and Screen Recording access.

Use Cases

Peekaboo excels in scenarios involving repetitive GUI interaction. Common use cases include:

• Automated Testing: Programmatically interacting with legacy macOS applications that lack modern APIs.
• Cross-App Orchestration: Moving data from a web browser to a desktop-native database or CRM that cannot be synced automatically.
• System Cleanup: Automated management of window positions, space switching, and clearing caches.
• Onboarding/Tutorials: Creating automated "walkthroughs" that click, type, and navigate through software as if a human were present.
• Dynamic Reporting: Capturing annotated screenshots of application states and storing them for audit trails.

Example Prompts

1. "Peekaboo, check the current status of my open windows. If you see the 'Report.numbers' window, bring it to the front and minimize the Safari browser."
2. "Use Peekaboo to identify the 'Submit' button on the current active dialog, click it, and then type the message 'Workflow completed' into the system clipboard."
3. "List all currently running apps, take a screenshot of the main screen for validation, and provide a JSON summary of the visible application windows."

Tips & Limitations

For the best results, always prioritize using element IDs (--id) rather than raw coordinates (--coords), as coordinates are brittle if window resolutions change. If you find the agent struggling with complex menus, use the peekaboo see --annotate command to generate a visual map that helps the agent identify targetable UI components. Note that Peekaboo requires Accessibility permissions to function correctly; if the tool appears stuck during a click operation, re-check your macOS System Settings. Be mindful that rapid automation can outpace system UI responsiveness; use --focus-retry-count to build resilient scripts that handle minor latency.