Reading the repo

Opening the box…

How to set up Peekaboo (openclaw/Peekaboo) · gitmanual

Assembly instructions

openclaw/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.

Node.jsSwift#ai#macos#mcp#screenshots

Difficulty: Moderate
Time: about 15 min
Stars: ★ 5,434
Activity: Updated this month
License: MIT
Open issues: 13
Got it running: Be the first
Looked up: 2 h ago

Saved setup from 2 h ago

Start here

Website ↗peekaboo.booThe project's own site.

Will it work on my device?

Yes, it installs on your macOS

A ready-made macOS download is in the latest release.

Checking for

Download for macOS

v4.9.7 · 10/23/2026 ↗

Peekaboo-4.9.7.dmg

dmg · 49.1 MB · 235 downloads · best match

Download

Drag the app into Applications.

curl -LO "https://github.com/openclaw/Peekaboo/releases/download/v4.9.7/Peekaboo-4.9.7.dmg"
open "Peekaboo-4.9.7.dmg"

Other macOS downloads (3)

peekaboo-macos-universal.tar.gz

tar.gz · Universal · 32.4 MB · 395 downloads

Download

Move the extracted binary onto your PATH (e.g. /usr/local/bin). If macOS blocks it: xattr -d com.apple.quarantine <binary>

curl -LO "https://github.com/openclaw/Peekaboo/releases/download/v4.9.7/peekaboo-macos-universal.tar.gz"
tar -xzf "peekaboo-macos-universal.tar.gz"

peekaboo-macos-arm64.tar.gz

tar.gz · Apple Silicon · 15.5 MB · 3,934 downloads

Download

Move the extracted binary onto your PATH (e.g. /usr/local/bin). If macOS blocks it: xattr -d com.apple.quarantine <binary>

curl -LO "https://github.com/openclaw/Peekaboo/releases/download/v4.9.7/peekaboo-macos-arm64.tar.gz"
tar -xzf "peekaboo-macos-arm64.tar.gz"

peekaboo-macos-x86_64.tar.gz

tar.gz · Intel · 16.9 MB · 144 downloads

Download

Move the extracted binary onto your PATH (e.g. /usr/local/bin). If macOS blocks it: xattr -d com.apple.quarantine <binary>

curl -LO "https://github.com/openclaw/Peekaboo/releases/download/v4.9.7/peekaboo-macos-x86_64.tar.gz"
tar -xzf "peekaboo-macos-x86_64.tar.gz"

Install with a package manager

Homebrew

brew install openclaw/tap/peekaboo

From the README, exactly as the maintainers wrote it.

Did you get it running?

No reports for macOS yet.

Still stuck? Get a written guide

Claude reads the 12 key files and writes a step-by-step guide for macOS. Once written, it's saved for everyone.

Parts list

1×Node.js >=22.0.0runtime
1×Swift runtime
1×pnpm pnpm@11.28.4package manager

Featured in Zain Finds

See the poster ↗Impressive... your AI can actually SEE your screen now? 😳

Share this manual

Good to know

Monorepo (workspaces) — install from the repo root.
Has AGENTS.md — instructions for coding agents. You can open Claude Code (or another agent) in the cloned folder and ask it to do the setup for you.

package.json scripts (46)

setup:swiftpython3 scripts/setup-swift-workspace.py setup
test:swift-workspacepython3 scripts/test-swift-workspace.py
test:log-scriptsbash scripts/test-playground-log-wrapper.sh && node --test tests/pblog.test.mjs tests/playground-log.test.mjs tests/pblog-error-stream.test.mjs
build:clipython3 scripts/setup-swift-workspace.py run -- swift build --package-path Apps/CLI
build:cli:releasepython3 scripts/setup-swift-workspace.py run -- swift build --configuration release --package-path Apps/CLI
build:swift./scripts/build-swift-arm.sh
build:swift:all./scripts/build-swift-universal.sh
app:restart./scripts/restart-peekaboo.sh
app:install-companion./scripts/restart-peekaboo.sh --deployment
buildpnpm run build:cli
test:safepnpm run setup:swift && pnpm run test:swift-workspace && pnpm run test:log-scripts && pnpm run test:ambient-state-policy && pnpm run test:mcp-wrapper && pnpm run test:guidance && pnpm run test:codeql-build-graph && pnpm run test:release-validation && pnpm run test:docs && pnpm run test:docs-site && node --test tests/homebrew-release-assets.test.mjs && scripts/test-source-provenance.sh && scripts/test-terminal-artifact-env.sh && scripts/test-release-version.sh && python3 scripts/test-release-archive-publication.py && scripts/test-read-macho-info-plist.sh && scripts/test-artifact-tree-manifest.sh && scripts/test-controller-source-manifest.sh && scripts/test-atomic-rename-exclusive.sh && scripts/test-terminal-artifact-policy.sh && node scripts/test-terminal-archive-policy.mjs && node scripts/test-terminal-dmg-payload.mjs && scripts/test-terminal-manifest-portability.sh && scripts/test-build-node-runtime-macos.sh && scripts/test-build-playground-artifact.sh && scripts/test-build-terminal-dmg.sh && scripts/test-notarize-terminal-artifact.sh && python3 scripts/test-notary-api-submit.py && scripts/test-release-signing-policy.sh && scripts/test-release-package-resolution.sh && scripts/test-codesign-with-retry.sh && scripts/test-sign-release-app.sh && scripts/test-swift-runtime-libraries.sh && python3 scripts/test-standalone-cli-install.py && scripts/test-restart-peekaboo.sh && scripts/test-swiftpm-consumer.sh && node --no-warnings scripts/test-chrome-devtools-mcp-contract.mjs && node --no-warnings scripts/test-browser-provider-connection.mjs && pnpm run test:release-preflight && pnpm run test:background-certification && swift test ${PEEKABOO_BUILD_JOBS:+--jobs "$PEEKABOO_BUILD_JOBS"} --package-path Core/PeekabooFoundation && PEEKABOO_INCLUDE_AUTOMATION_TESTS=true PEEKABOO_INCLUDE_AMBIENT_STATE_TESTS=false swift test ${PEEKABOO_BUILD_JOBS:+--jobs "$PEEKABOO_BUILD_JOBS"} --package-path Apps/CLI -Xswiftc -DPEEKABOO_SKIP_AUTOMATION --no-parallel
test:mcp-wrappernode --test tests/peekaboo-mcp-*.test.mjs
test:ambient-state-policynode --test tests/ambient-state-test-policy.test.mjs
test:guidancenode --test tests/background-capability-guidance.test.mjs tests/subprocess-integration-guidance.test.mjs
test:codeql-build-graphnode --test tests/codeql-build-graph.test.mjs
test:release-validationnode --test tests/release-validation-workflow.test.mjs
test:docs-sitenode --test tests/docs-site-*.test.mjs
test:release-preflightnode --test tests/release-preflight-contract.test.mjs
test:background-certificationscripts/test-background-certification.sh
test:automationpnpm run setup:swift && PEEKABOO_INCLUDE_AUTOMATION_TESTS=true swift test --package-path Apps/CLI --no-parallel
test:automation:readpnpm run setup:swift && RUN_AUTOMATION_READ=true PEEKABOO_INCLUDE_AUTOMATION_TESTS=true swift test --package-path Apps/CLI --no-parallel
test:automation:inputpnpm run setup:swift && PEEKABOO_INCLUDE_AUTOMATION_TESTS=true PEEKABOO_RUN_INPUT_AUTOMATION_TESTS=true swift test --package-path Core/PeekabooCore --no-parallel
test:automation:localpnpm run setup:swift && bash -lc 'BIN_PATH=$(swift build --package-path Apps/CLI --show-bin-path) && RUN_LOCAL_TESTS=true PEEKABOO_INCLUDE_AUTOMATION_TESTS=true PEEKABOO_RUN_INPUT_AUTOMATION_TESTS=true PEEKABOO_CLI_PATH="$BIN_PATH/peekaboo" swift test --package-path Apps/CLI --no-parallel'
test:allpnpm run setup:swift && bash -lc 'set -euo pipefail; cd Apps/CLI && swift test -Xswiftc -DPEEKABOO_SKIP_AUTOMATION --no-parallel && PEEKABOO_INCLUDE_AUTOMATION_TESTS=true swift test --no-parallel'
testpnpm run test:safe

Files we read (12)

.github/workflows/clawsweeper-dispatch.yml

.github/workflows/codeql.yml

.github/workflows/commander-multiplatform.yml

.github/workflows/crabbox-hydrate.yml

.github/workflows/macos-ci.yml

.github/workflows/macos26-artifact-smoke.yml

.gitmodules

Package.swift

README.md

docs/install.md

package.json

pnpm-workspace.yaml

Branch main · 2,591 files in the repo