Skip to content
Back to search

Peekaboo

Peekaboo is a macOS CLI & optional MCP server that enables AI agents to capture screenshots of applications, or the entire system, with optional visual question answering through local or remote AI models.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/openclaw/Peekaboo with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/openclaw/Peekaboo'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/openclaw--peekaboo/badge.svg)](/listings/openclaw--peekaboo)

HTML

<a href="/listings/openclaw--peekaboo"><img src="/api/listings/openclaw--peekaboo/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The released CLI and app require macOS 15 or later.

CLI with Homebrew

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.

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).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 135 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Peekaboo 🫣 — Mac automation that sees the screen and does the clicks.
  2. [![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)
  3. 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.
  4. ![Peekaboo banner](assets/peekaboo.png)
  5. ## Install
  6. The released CLI and app require macOS 15 or later.
  7. ### CLI with Homebrew
  8. ```sh
  9. brew install openclaw/tap/peekaboo
  10. ```
  11. ### MCP package with npm
  12. The npm package requires Node.js 22 or later and includes the CLI plus its MCP launcher.
  13. ```sh
  14. npx -y @steipete/peekaboo --version
  15. ```
  16. See [MCP setup](docs/MCP.md) to connect it to Codex, Claude Code, Cursor, or another MCP client.
  17. ### Mac app
  18. 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`.
  19. For source builds and alternative install details, see the [installation guide](docs/install.md).
  20. ## Quick start
  21. Check the permissions available to Peekaboo, then take a screenshot:
  22. ```sh
  23. peekaboo permissions status
  24. peekaboo see --no-elements --mode screen --path /tmp/peekaboo-screen.png
  25. ```
  26. 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.
  27. Inspect a running app to get a structured UI map with opaque element IDs:
  28. ```sh
  29. peekaboo see --app Finder --json
  30. ```
  31. That is the core loop: observe the current screen, choose an element from the result, and act on it.
  32. ## What's new in 4.9.9
  33. Peekaboo 4.9.9 is a fix release. Peekaboo.app no longer crashes when a Bridge client inspects the app's own Settings window. `action` can now invoke UIKit and Mac Catalyst custom accessibility actions by their title, fresh `see` accepts localized Chrome profile window titles, and exact-window target-change failures now include a typed JSON diagnostic saying which check failed and how. In the Mac app, Ollama model discovery refreshes when its base URL changes, Settings is found by its identity instead of its window title, and Launch at Login stays off until macOS approves it.
  34. ## Automate an app
  35. List Safari's windows, copy the intended `window_id` (`12345` below), then keep the entire interaction pinned to
  36. that exact window:
  37. ```sh
  38. peekaboo window list --app Safari --json
  39. peekaboo click "Address and search bar" --app Safari --window-id 12345
  40. peekaboo type "github.com/openclaw/Peekaboo" --app Safari --window-id 12345
  41. peekaboo press Return --app Safari --window-id 12345
  42. ```
  43. Targeted semantic and typed CLI input uses background delivery when Peekaboo can resolve the process, so the app does
  44. not have to become frontmost. Raw CLI `press` chords can also stay background with an exact window selector. The CLI
  45. also accepts a fresh exact non-dialog snapshot; that snapshot is required by background-only Agent/MCP policy.
  46. App/PID-only and targetless chords require explicit foreground consent, as do window-selector-only Agent/MCP chords.
  47. Prefer a semantic action such as `menu click` when one exists. See the
  48. [automation guide](docs/automation.md) for element IDs, coordinates, snapshots, waits, and input behavior.
  49. ## Agent and MCP
  50. The agent combines the same observation and action tools into a natural-language run:
  51. ```sh
  52. peekaboo agent "Open Safari, go to github.com, and search for Peekaboo" --allow-foreground
  53. ```
  54. Agent runs need a configured model provider. See [agent setup](docs/commands/agent.md) for providers and sessions, or [MCP setup](docs/MCP.md) to expose Peekaboo's tools to another client.
  55. ## Command map
  56. | Goal | Commands | Guide |
  57. | --- | --- | --- |
  58. | Observe the desktop | `see`, `screen list`, `window list` | [Capture and inspection](docs/quickstart.md) |
  59. | Interact with UI | `click`, `type`, `press`, `scroll`, `drag`, `set-value`, `action` | [Automation](docs/automation.md) |
  60. | Control macOS | `app`, `window`, `menu`, `menubar`, `dock`, `dialog`, `space` | [Command reference](docs/commands/README.md) |
  61. | Run workflows | `agent`, `capture` | [Agent](docs/commands/agent.md) · [Capture](docs/commands/capture.md) |
  62. | Integrate with clients | `mcp`, `browser`, `tools` | [MCP](docs/MCP.md) |
  63. Run `peekaboo help <command>` for live CLI help. The [complete command index](docs/commands/README.md) links to flags, examples, and troubleshooting for every command.
  64. ## Configuration
  65. Peekaboo stores provider credentials and settings under `~/.peekaboo`. Use `peekaboo config` to inspect or change them, and consult the [configuration guide](docs/configuration.md) for profiles, environment variables, and custom providers. The [provider reference](docs/providers.md) covers hosted, compatible, and local model backends.
  66. Shell completions for zsh, bash, and fish come from `peekaboo completions`; see the [completion guide](docs/commands/completions.md) for persistent setup.
  67. ## Learn more
  68. - [Project direction](VISION.md)
  69. - [Platform support](docs/platform-support.md)
  70. - [Architecture](docs/ARCHITECTURE.md)
  71. - [Building from source](docs/building.md)
  72. - [Testing](docs/testing/tools.md)
  73. - [Agent chat loop](docs/agent-chat.md)
  74. - [Command reference](docs/cli-command-reference.md)
  75. ## Community
  76. - [PeekabooWin](https://github.com/FelixKruger/PeekabooWin) — Windows-first rewrite of the Peekaboo automation loop (JavaScript + PowerShell) by [@FelixKruger](https://github.com/FelixKruger)
  77. - [PeekabooX](https://github.com/nordbyte/PeekabooX) — Linux-first rewrite of the Peekaboo automation loop (Rust + Python) by [@nordbyte](https://github.com/nordbyte)
  78. ## Development
  79. Source builds require macOS 15 or later, Swift 6.2 or later, Node.js 22 or later, and the repository's submodules.
  80. ```sh
  81. pnpm install --frozen-lockfile
  82. pnpm run build:cli
  83. pnpm run lint:docs
  84. pnpm run test:safe
  85. ```
  86. More build, signing, and test details live in [docs/building.md](docs/building.md).
  87. ## License
  88. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.