peekaboo

Automates macOS GUI interactions, screen capture, and UI element targeting via CLI.

1|Updated Jun 29, 2026
One-click install
npx skills add https://github.com/coreyone/software-maestro --skill peekaboo-coreyone
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: peekaboo
Source: https://github.com/coreyone/software-maestro/tree/main/quality/peekaboo
Command: npx skills add https://github.com/coreyone/software-maestro --skill peekaboo-coreyone

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Automating native macOS desktop applications and simulators normally requires manual clicking, typing, and screenshot capture, which cannot be scripted reliably. Peekaboo provides a CLI that captures screens, identifies UI elements, and drives mouse and keyboard input programmatically. ## Core Features & Use Cases - Screen Capture & Inspection: Capture screenshots of screens, windows, or menu bar regions, and generate annotated UI maps with element IDs via the see command. - Input Automation: Click, type, drag, scroll, swipe, and send hotkeys to targeted UI elements by ID, query, or coordinates. - App & Window Management: Launch, quit, focus, move, and resize applications and windows, plus interact with menus, Dock, and system dialogs. - Use Case: Automate a login flow in Safari by running peekaboo see --annotate to identify the form fields, then peekaboo click and peekaboo type to fill in credentials and submit. ## Quick Start Ask the agent to capture an annotated screenshot of a macOS app window and then click a specific button and type text into a field using Peekaboo commands.

Frequently Asked Questions about peekaboo

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

FAQPage Schema
How do I automate clicking a button in a macOS app from the command line?▼

Run `peekaboo see --annotate` to capture an annotated UI map with element IDs, then use `peekaboo click --on <element-id> --app <name>` to click the target. You can also target by coordinates with `--coords x,y`.

How to capture a screenshot of a specific macOS application window?▼

Use `peekaboo image --app <name> --window-title <title> --path output.png` to capture a specific window. Add `--retina` for high resolution or `--analyze "prompt"` to get an AI description of the capture.

What permissions does Peekaboo need on macOS?▼

Peekaboo requires Screen Recording and Accessibility permissions to capture screens and control UI elements. Run `peekaboo permissions` to check the current status of both permissions.

Can Peekaboo type text and send keyboard shortcuts?▼

Yes, `peekaboo type` enters text with options like `--clear`, `--delay`, and `--wpm`, while `peekaboo hotkey --keys "cmd,shift,t"` sends modifier combinations and `peekaboo press` handles special keys like escape or tab.

Why does peekaboo click fail to find my UI element?▼

Element IDs come from a snapshot, so run `peekaboo see --annotate` first to get fresh IDs for the current UI state. If the window moved or content changed, capture a new snapshot or target by coordinates instead.

Does Peekaboo support scripting and JSON output?▼

Yes, most commands accept `--json` for machine-readable output, and `peekaboo run` executes `.peekaboo.json` script files for repeatable automation sequences.