Peekaboo is a macOS automation tool written in Swift that combines screenshot capture, AI analysis, and GUI automation capabilities. The project provides both a command-line interface and an optional Model Context Protocol (MCP) server, enabling AI agents to interact with macOS applications and the system through visual understanding and automated actions. The tool is designed to support AI-driven workflows where agents need to see what is on screen and perform clicks, typing, and other interactions in response.
The core functionality centers on pixel-accurate screen capture with optional Retina 2x scaling, supporting captures of individual windows, full screens, and the menu bar. Peekaboo integrates optional visual question answering through local or remote AI models, allowing natural-language agents to chain together multiple automation tools. The automation capabilities include clicking, typing, scrolling, hotkey execution, menu interaction, window management, and app launching. A key architectural feature is the distinction between background and foreground input delivery, where background delivery targets specific processes without stealing focus when the target application is known, while foreground delivery is used when applications require focused key windows or real foreground mouse events.
The project supports multiple AI providers through Tachikoma, including hosted services, local models, and endpoints compatible with OpenAI and Anthropic APIs. Version 3 introduced native agent flows and multi-screen automation across both the CLI and MCP server. The tool requires macOS Screen Recording and Accessibility permissions, with additional Event Synthesizing permissions needed for certain input types. Configuration is managed through a JSON-based system shared between the macOS app and CLI, with settings for AI provider credentials, model selection, and agent generation parameters like temperature and maximum tokens.
The repository overlaps with other projects including anthropics/claude-code, tldraw/tldraw, and openclaw/openclaw through shared contributors.
The project is classified across multiple security and development domains including debugger detection, anti-debugging, app security, iOS and macOS development, reverse engineering, code protection, and runtime protection. The tool includes comprehensive documentation covering permissions, building from source, testing, MCP setup, and local model integration with Ollama. Community-driven ports exist for Windows (PeekabooWin) and Linux (PeekabooX), indicating broader interest in the automation paradigm beyond macOS. The project is licensed under MIT and uses pnpm for dependency management with development workflows for linting, formatting, and testing.
