Peekaboo

# Peekaboo 🫣 — Mac automation that sees the screen and does the clicks.

[![CI](https://img.shields.io/github/actions/workflow/status/openclaw/Peekaboo/macos-ci.yml?branch=main&style=flat-square&label=ci)](https://github.com/openclaw/Peekaboo/actions/workflows/macos-ci.yml) [![npm](https://img.shields.io/npm/v/%40steipete%2Fpeekaboo?style=flat-square)](https://www.npmjs.com/package/@steipete/peekaboo) [![GitHub release](https://img.shields.io/github/v/release/openclaw/Peekaboo?style=flat-square)](https://github.com/openclaw/Peekaboo/releases/latest) [![macOS 15+](https://img.shields.io/badge/macOS-15%2B-0078d7?logo=apple&logoColor=white&style=flat-square)](docs/platform-support.md) [![Swift 6.2](https://img.shields.io/badge/Swift-6.2-F05138?logo=swift&logoColor=white&style=flat-square)](https://swift.org/) [![Node](https://img.shields.io/node/v/%40steipete%2Fpeekaboo?style=flat-square)](https://nodejs.org/) [![License](https://img.shields.io/github/license/openclaw/Peekaboo?style=flat-square)](LICENSE) [![Homebrew](https://img.shields.io/badge/Homebrew-openclaw%2Ftap-b28f62?logo=homebrew&logoColor=white&style=flat-square)](https://github.com/openclaw/homebrew-tap) [![Ask DeepWiki](https://img.shields.io/badge/Ask-DeepWiki-0088cc?style=flat-square)](https://deepwiki.com/openclaw/Peekaboo)

Peekaboo is a macOS CLI and menu-bar app for screen capture, accessibility inspection, and native UI automation. Use it directly, let its agent plan multi-step work, or expose the same toolset to MCP clients.

![Peekaboo banner](assets/peekaboo.png)

## Install

The released CLI and app require macOS 15 or later.

### CLI with Homebrew

```sh
brew install openclaw/tap/peekaboo
```

### MCP package with npm

The npm package requires Node.js 22 or later and includes the CLI plus its MCP launcher.

```sh
npx -y @steipete/peekaboo --version
```

See [MCP setup](docs/MCP.md) to connect it to Codex, Claude Code, Cursor, or another MCP client.

### Mac app

Download the signed DMG from the [latest GitHub release](https://github.com/openclaw/Peekaboo/releases/latest). The menu-bar app provides permission onboarding, visual feedback, and agent sessions; install the CLI separately when you also need `peekaboo` on `PATH`.

For source builds and alternative install details, see the [installation guide](docs/install.md).

## Quick start

Check the permissions available to Peekaboo, then take a screenshot:

```sh
peekaboo permissions status
peekaboo see --no-elements --mode screen --path /tmp/peekaboo-screen.png
```

Screen capture requires Screen Recording permission. Accessibility permission enables UI inspection and control; the [permissions guide](docs/permissions.md) covers setup and the additional permission used for synthetic input.

Inspect a running app to get a structured UI map with opaque element IDs:

```sh
peekaboo see --app Finder --json
```

That is the core loop: observe the current screen, choose an element from the result, and act on it.

## What's new in 4