{"id":49675503,"url":"https://github.com/openclaw/peekaboo","last_synced_at":"2026-05-24T06:03:47.937Z","repository":{"id":294915015,"uuid":"988488798","full_name":"openclaw/Peekaboo","owner":"openclaw","description":"Peekaboo is a macOS CLI \u0026 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.","archived":false,"fork":false,"pushed_at":"2026-05-20T03:03:58.000Z","size":629352,"stargazers_count":4405,"open_issues_count":1,"forks_count":331,"subscribers_count":15,"default_branch":"main","last_synced_at":"2026-05-21T08:40:22.231Z","etag":null,"topics":["ai","macos","mcp","screenshots","swift"],"latest_commit_sha":null,"homepage":"http://www.peekaboo.boo","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openclaw.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["moltbot"]}},"created_at":"2025-05-22T16:09:06.000Z","updated_at":"2026-05-21T08:29:54.000Z","dependencies_parsed_at":"2025-07-06T12:33:50.589Z","dependency_job_id":"b5276ed9-6c52-4ca8-ade2-fa00e75cf363","html_url":"https://github.com/openclaw/Peekaboo","commit_stats":null,"previous_names":["steipete/peekaboo","openclaw/peekaboo"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/openclaw/Peekaboo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2FPeekaboo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2FPeekaboo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2FPeekaboo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2FPeekaboo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openclaw","download_url":"https://codeload.github.com/openclaw/Peekaboo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2FPeekaboo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33423286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","macos","mcp","screenshots","swift"],"created_at":"2026-05-07T02:00:48.555Z","updated_at":"2026-05-24T06:03:47.925Z","avatar_url":"https://github.com/openclaw.png","language":"Swift","funding_links":["https://github.com/sponsors/moltbot"],"categories":[],"sub_categories":[],"readme":"# Peekaboo 🫣 - Mac automation that sees the screen and does the clicks.\n\n![Peekaboo Banner](assets/peekaboo.png)\n\n[![npm package](https://img.shields.io/badge/npm_package-3.2.3-brightgreen?logo=npm\u0026logoColor=white\u0026style=flat-square)](https://www.npmjs.com/package/@steipete/peekaboo)\n[![License: MIT](https://img.shields.io/badge/License-MIT-ffd60a?style=flat-square)](https://opensource.org/licenses/MIT)\n[![macOS 15.0+ (Sequoia)](https://img.shields.io/badge/macOS-15.0%2B_(Sequoia)-0078d7?logo=apple\u0026logoColor=white\u0026style=flat-square)](https://www.apple.com/macos/)\n[![Swift 6.2](https://img.shields.io/badge/Swift-6.2-F05138?logo=swift\u0026logoColor=white\u0026style=flat-square)](https://swift.org/)\n[![node \u003e=22](https://img.shields.io/badge/node-%3E%3D22.0.0-2ea44f?logo=node.js\u0026logoColor=white\u0026style=flat-square)](https://nodejs.org/)\n[![Download macOS](https://img.shields.io/badge/Download-macOS-000000?logo=apple\u0026logoColor=white\u0026style=flat-square)](https://github.com/steipete/peekaboo/releases/latest)\n[![Homebrew](https://img.shields.io/badge/Homebrew-steipete%2Ftap-b28f62?logo=homebrew\u0026logoColor=white\u0026style=flat-square)](https://github.com/steipete/homebrew-tap)\n[![Ask DeepWiki](https://img.shields.io/badge/Ask-DeepWiki-0088cc?style=flat-square)](https://deepwiki.com/steipete/peekaboo)\n\nPeekaboo brings high-fidelity screen capture, AI analysis, and complete GUI automation to macOS. Version 3 adds native agent flows and multi-screen automation across the CLI and MCP server.\n\n## What you get\n- Pixel-accurate captures (windows, screens, menu bar) with optional Retina 2x scaling.\n- Natural-language agent that chains Peekaboo tools (see, click, type, scroll, hotkey, menu, window, app, dock, space).\n- Action-first UI automation for routine clicks/scrolls, with synthetic input fallback for apps that need it.\n- Direct accessibility tools for settable values and named actions (`set-value`, `perform-action`).\n- Menu and menubar discovery with structured JSON; no clicks required.\n- Multi-provider AI through Tachikoma, including hosted, local, and OpenAI-/Anthropic-compatible providers.\n- MCP server for Codex, Claude Code, and Cursor plus a native CLI; the same tools in both.\n- Configurable, testable workflows with reproducible sessions and strict typing.\n- Requires macOS Screen Recording + Accessibility permissions (see [docs/permissions.md](docs/permissions.md)).\n\n## Install\n- macOS app + CLI (Homebrew):\n  ```bash\n  brew install steipete/tap/peekaboo\n  ```\n- MCP server (Node 22+, no global install needed):\n  ```bash\n  npx -y @steipete/peekaboo\n  ```\n\n## Quick start\n```bash\n# Capture full screen at Retina scale and save to Desktop\npeekaboo image --mode screen --retina --path ~/Desktop/screen.png\n\n# Click a button by label (captures, resolves, and clicks in one go)\npeekaboo see --app Safari --json | jq -r '.data.snapshot_id' | read SNAPSHOT\npeekaboo click --on \"Reload this page\" --snapshot \"$SNAPSHOT\"\n\n# Directly set a text field value when the accessibility value is settable\npeekaboo set-value --on T1 --value \"hello\" --snapshot \"$SNAPSHOT\"\n\n# Invoke a named accessibility action on an element\npeekaboo perform-action --on B1 --action AXPress --snapshot \"$SNAPSHOT\"\n\n# Run a natural-language automation\npeekaboo agent \"Open Notes and create a TODO list with three items\"\n\n# Run as an MCP server (Codex, Claude Code, Cursor)\nnpx -y @steipete/peekaboo\n\n# Minimal MCP client config snippet:\n# {\n#   \"mcpServers\": {\n#     \"peekaboo\": {\n#       \"command\": \"npx\",\n#       \"args\": [\"-y\", \"@steipete/peekaboo\"],\n#       \"env\": {\n#         \"PEEKABOO_AI_PROVIDERS\": \"openai/gpt-5.5,anthropic/claude-opus-4-7\"\n#       }\n#     }\n#   }\n# }\n```\n\n## Shell completions\n\nPeekaboo can generate shell-native completions directly from the same Commander\nmetadata that powers CLI help and docs:\n\n```bash\n# Current shell (recommended)\neval \"$(peekaboo completions $SHELL)\"\n\n# Explicit shells\neval \"$(peekaboo completions zsh)\"\neval \"$(peekaboo completions bash)\"\npeekaboo completions fish | source\n```\n\nFor persistent setup and troubleshooting, see\n[docs/commands/completions.md](docs/commands/completions.md).\n\n| Command | Key flags / subcommands | What it does |\n| --- | --- | --- |\n| [see](docs/commands/see.md) | `--app`, `--mode screen/window`, `--retina`, `--json` | Capture and annotate UI, return snapshot + element IDs |\n| [click](docs/commands/click.md) | `--on \u003cid/query\u003e`, `--snapshot`, `--wait-for`, `--coords` | Click by element ID, label, or coordinates |\n| [type](docs/commands/type.md) | `--text`, `--clear`, `--profile`, `--delay` | Enter text with pacing options |\n| [set-value](docs/commands/set-value.md) | `--on \u003cid/query\u003e`, `--value`, `--snapshot` | Directly set a settable accessibility value |\n| [perform-action](docs/commands/perform-action.md) | `--on \u003cid/query\u003e`, `--action`, `--snapshot` | Invoke a named accessibility action |\n| [press](docs/commands/press.md) | key names, `--count`, `--delay`, `--hold` | Special keys and sequences |\n| [hotkey](docs/commands/hotkey.md) | combos like `cmd,shift,t` | Modifier combos (cmd/ctrl/alt/shift) |\n| [scroll](docs/commands/scroll.md) | `--on \u003cid\u003e`, `--direction up/down`, `--amount` | Scroll views or elements |\n| [swipe](docs/commands/swipe.md) | `--from/--to`, `--duration`, `--steps` | Smooth gesture-style drags |\n| [drag](docs/commands/drag.md) | `--from/--to`, modifiers, Dock/Trash targets | Drag-and-drop between elements/coords |\n| [move](docs/commands/move.md) | `--to \u003cid/coords\u003e`, `--screen-index` | Position the cursor without clicking |\n| [window](docs/commands/window.md) | `list`, `move`, `resize`, `focus`, `set-bounds` | Move/resize/focus windows and Spaces |\n| [app](docs/commands/app.md) | `launch`, `quit`, `relaunch`, `switch`, `list` | Launch, quit, relaunch, switch apps |\n| [space](docs/commands/space.md) | `list`, `switch`, `move-window` | List or switch macOS Spaces |\n| [menu](docs/commands/menu.md) | `list`, `list-all`, `click`, `click-extra` | List/click app menus and extras |\n| [menubar](docs/commands/menubar.md) | `list`, `click` | Target status-bar items by name/index |\n| [dock](docs/commands/dock.md) | `launch`, `right-click`, `hide`, `show`, `list` | Interact with Dock items |\n| [dialog](docs/commands/dialog.md) | `list`, `click`, `input`, `file`, `dismiss` | Drive system dialogs (open/save/etc.) |\n| [image](docs/commands/image.md) | `--mode screen/window/menu`, `--retina`, `--analyze` | Screenshot screen/window/menu bar (+analyze) |\n| [list](docs/commands/list.md) | `apps`, `windows`, `screens`, `menubar`, `permissions` | Enumerate apps, windows, screens, permissions |\n| [tools](docs/commands/tools.md) | `--verbose`, `--json`, `--no-sort` | Inspect native Peekaboo tools |\n| [completions](docs/commands/completions.md) | `[shell]` | Generate zsh/bash/fish completion scripts from Commander metadata |\n| [config](docs/commands/config.md) | `init`, `show`, `add`, `login`, `models` | Manage credentials/providers/settings |\n| [permissions](docs/commands/permissions.md) | `status`, `grant` | Check/grant required macOS permissions |\n| [run](docs/commands/run.md) | `.peekaboo.json`, `--output`, `--no-fail-fast` | Execute `.peekaboo.json` automation scripts |\n| [sleep](docs/commands/sleep.md) | `--duration` (ms) | Millisecond delays between steps |\n| [clean](docs/commands/clean.md) | `--all-snapshots`, `--older-than`, `--snapshot` | Prune snapshots and caches |\n| [agent](docs/commands/agent.md) | `--model`, `--dry-run`, `--resume`, `--max-steps`, audio | Natural-language multi-step automation |\n| [mcp](docs/commands/mcp.md) | `serve` (default) | Run Peekaboo as an MCP server |\n\n## Models and providers\n\nPeekaboo's provider list changes with Tachikoma and the tested model catalog. See\n[docs/providers.md](docs/providers.md) for the current provider reference, including OpenAI, Anthropic, xAI/Grok,\nGoogle Gemini, MiniMax, Ollama, LM Studio, and compatible custom endpoints.\n\nSet providers via `PEEKABOO_AI_PROVIDERS` or `peekaboo config add`.\n\n## Learn more\n- Command reference: [docs/commands/](docs/commands/)\n- Platform support: [docs/platform-support.md](docs/platform-support.md)\n- Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)\n- Building from source: [docs/building.md](docs/building.md)\n- Testing guide: [docs/testing/tools.md](docs/testing/tools.md)\n- MCP setup: [docs/commands/mcp.md](docs/commands/mcp.md)\n- Permissions: [docs/permissions.md](docs/permissions.md)\n- Ollama/local models: [docs/ollama.md](docs/ollama.md)\n- Agent chat loop: [docs/agent-chat.md](docs/agent-chat.md)\n- Service API reference: [docs/service-api-reference.md](docs/service-api-reference.md)\n\n## Community\n\n- [PeekabooWin](https://github.com/FelixKruger/PeekabooWin) — Windows-first rewrite of the Peekaboo automation loop (JavaScript + PowerShell) by [@FelixKruger](https://github.com/FelixKruger)\n- [PeekabooX](https://github.com/nordbyte/PeekabooX) — Linux-first rewrite of the Peekaboo automation loop (Rust + Python) by [@nordbyte](https://github.com/nordbyte)\n\n## Development basics\n- Requirements: see [docs/platform-support.md](docs/platform-support.md). Node 22+ is only needed for the npm MCP wrapper and pnpm helper scripts.\n- Install deps: `pnpm install` then `pnpm run build:cli` or `pnpm run test:safe`.\n- Lint/format: `pnpm run lint \u0026\u0026 pnpm run format`.\n\n## License\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenclaw%2Fpeekaboo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenclaw%2Fpeekaboo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenclaw%2Fpeekaboo/lists"}