peekaboo

Automate macOS UI interactions with an observe-act-verify loop and JSON output.

7|2|Updated Feb 25, 2026
One-click install
npx skills add https://github.com/wenerme/ai --skill peekaboo-wenerme
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: peekaboo
Source: https://github.com/wenerme/ai/tree/main/skills/peekaboo
Command: npx skills add https://github.com/wenerme/ai --skill peekaboo-wenerme

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Peekaboo automates macOS user interface tasks like clicking, typing, window/menu navigation, permissions setup, and UI inspection so you don’t have to perform repetitive manual steps.

Core Features & Use Cases

  • UI discovery and inspection: Use list and see to locate apps, windows, screens, menus, and interactive elements (with refreshed element IDs after changes) for reliable targeting.
  • Deterministic UI actions with verification: Follow observe → act → verify to click, type, paste, press hotkeys, scroll, drag, and interact with dialogs/panels while reducing flaky automation.
  • Permission and Bridge troubleshooting: Use permissions status and Bridge status to diagnose failures related to macOS TCC requirements and host/remote execution differences.
  • Agent and MCP tooling: Run Peekaboo as an MCP server or use agent-oriented commands for higher-level automation while still respecting safety/confirmation rules for destructive actions.

Quick Start

Ask the AI agent to use Peekaboo to open the target app, observe the relevant UI with a fresh element map, perform the required click or typing action using element IDs, and then verify the result with a new see or list output.

Frequently Asked Questions about peekaboo

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I automate macOS UI interactions without relying on screen coordinates?

macOS UI automation can be performed by inspecting UI state to locate interactive elements, executing targeted actions using element IDs, and verifying outcomes through an observe-act-verify loop. This non-coordinate-first approach reduces flaky automation by dynamically refreshing element IDs.

What's the best way to troubleshoot macOS automation failures caused by missing permissions?

To troubleshoot macOS automation failures, check the TCC-aware permissions status and Bridge host status. Diagnosing these requirements helps resolve failures related to accessibility permissions and host or remote execution differences.

Can I use an MCP server to orchestrate macOS window and menu control for AI agents?

Yes, you can run macOS automation as an MCP server to handle app, window, menu, and dialog control for agents. It provides agent-oriented commands for higher-level automation while respecting safety rules for destructive actions.

How do I locate and interact with specific UI elements during macOS automation?

You locate UI elements by using discovery commands to list apps, windows, screens, and menus. After identifying the target, you interact by clicking, typing, or pressing hotkeys, then verify the result with a new inspection output.

Why does my macOS UI automation fail during remote execution or Bridge host operations?

macOS UI automation fails during remote execution due to Bridge host differences and unmet TCC permissions. Checking the Bridge status and verifying accessibility permissions will diagnose these host-specific execution failures.