Peekaboo documentation

Peekaboo is a macOS automation toolkit for humans and agents. It captures pixels, reads the accessibility tree, drives input, and ships an agent runtime plus an MCP server so AI clients (Codex, Claude Code, Cursor) can drive the desktop with the same primitives you'd use from the shell.

TL;DR — brew install steipete/tap/peekaboo, grant Screen Recording + Accessibility, then peekaboo agent "open Safari and search for Peekaboo".

#Where to start

• Install — Homebrew, npm/MCP, source builds.
• Quickstart — first capture, first click, first agent run in five minutes.
• Permissions — what to grant, why, and how to verify.
• Configuration — environment variables, config files, credential storage.

#What Peekaboo does

• Capture & vision — pixel-accurate screen, window, and menu-bar capture; annotated AX maps.
• Automation — click, type, scroll, drag, hotkeys, menus, dialogs, windows, Spaces.
• Agent — natural-language plan/act loop with provider switching, resumable sessions, and visualizer feedback.
• MCP — expose every Peekaboo tool over stdio for Codex, Claude Code, and Cursor.

#Reference

• Command reference — every CLI command, grouped.
• Command index — one page per command with flags and examples.
• Architecture — Core, CLI, Bridge, Daemon, Visualizer.
• Releasing — versioning, signing, distribution.

#Surfaces

#Get help

• File issues: github.com/steipete/Peekaboo/issues
• Source: github.com/steipete/Peekaboo
• Author: @steipete