# peekaboo
> macOS screenshot capture, AI visual analysis, and GUI automation CLI

## Summary
macOS GUI automation tool providing pixel-accurate screen capture, AI-powered visual analysis, and 25+ automation commands for clicks, typing, window management, and natural language task execution.

## Capabilities
- Capture pixel-accurate screenshots of windows, screens, and menu bars with optional Retina 2x scaling
- Visual question-answering using multiple AI providers (OpenAI, Anthropic, Google, xAI, Ollama)
- GUI automation: click, type, press keys, hotkey combos, scroll, swipe, drag-and-drop
- Window management: list, move, resize, focus windows and Spaces
- Application control: launch, quit, relaunch, switch apps
- Structured JSON extraction of menus and menu bar items without clicking
- Natural language task execution for complex multi-step workflows
- MCP server mode for integration with Claude Desktop, Cursor, and other MCP clients
- JSON automation script execution for reproducible workflows

## When to Use
- An AI agent needs to see and interact with the macOS GUI
- Automating multi-step GUI workflows that cannot be done via CLI alone
- Capturing screenshots for documentation or testing
- Querying screen content with visual AI (e.g., reading dialog text, finding buttons)
- Integrating macOS GUI control into MCP-based agent workflows

## When NOT to Use
- Running on non-macOS platforms
- The task can be accomplished through existing CLI tools without GUI interaction
- Running in headless CI environments without a display
- macOS version is older than 15.0 (Sequoia)

## Usage Patterns
### Capture a screenshot
```
peekaboo image --mode screen --retina --path ~/Desktop/screen.png
```
Takes a Retina-resolution screenshot of the full screen and saves it

### Click a button by label
```
peekaboo click --on "OK" --snapshot latest
```
Clicks the button labeled OK using the latest UI snapshot

### Execute a natural language task
```
peekaboo "Open Notes and create a TODO list with three items"
```
Uses AI to interpret and execute a multi-step GUI workflow

### List all windows
```
peekaboo windows list --json
```
Returns JSON listing of all open windows with positions and sizes

## Input / Output
- **stdin**: Not typically used
- **stdout**: JSON snapshots, screenshots (file paths), execution results
- **stderr**: Status and diagnostic messages

## Installation
- **homebrew**: `brew install steipete/tap/peekaboo`
- **npx**: `npx -y @steipete/peekaboo`

## Related Tools
- [summarize](/tools/summarize) (complementary): Summarize can process screenshots captured by Peekaboo

---
Source: https://littlescripts.sh/tools/peekaboo
