[{"_1":2,"_453":-5,"_454":-5},"loaderData",{"_3":4,"_24":25,"_274":275},"root",{"_5":6,"_7":8},"toasts",[],"visitor",{"_9":10,"_11":12},"viewportWidth",1280,"visitorSession",{"_13":14,"_16":17,"_18":-5,"_19":20,"_21":22,"_23":-5},"attributes",[15],"bot","id",27182804,"membership","referenceId","019ab33c-32bd-768e-80e6-9ee61bfabc38","unreadReleaseNotesCount",2,"userAccount","routes/_public/mcp/servers/~namespace/~slug/_pages/_layout",{"_26":27,"_28":-5,"_29":30,"_31":43,"_192":193,"_272":273},"availableLocales",[],"githubUser","locale",{"_31":32,"_39":40,"_41":42},"mcpServer",{"_33":34,"_35":36,"_37":38},"description","A macOS utility that captures screenshots and analyzes them with AI vision, enabling AI assistants to see and interpret what's on your screen.","displayName","Peekaboo MCP","readme","# Peekaboo MCP: Lightning-fast macOS Screenshots & GUI Automation 🚀\n\n![Peekaboo Banner](https://raw.githubusercontent.com/steipete/peekaboo/main/assets/banner.png)\n\n[![npm version](https://badge.fury.io/js/%40steipete%2Fpeekaboo-mcp.svg)](https://www.npmjs.com/package/@steipete/peekaboo-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![macOS (Sonoma)](https://img.shields.io/badge/macOS-14.0%2B%20(Sonoma)-blue.svg)](https://www.apple.com/macos/)\n[![Swift](https://img.shields.io/badge/Swift-6.2-orange.svg)](https://swift.org/)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)\n[![Download for macOS](https://img.shields.io/badge/Download-macOS-black?logo=apple)](https://github.com/steipete/peekaboo/releases/latest)\n[![Homebrew](https://img.shields.io/badge/Homebrew-steipete%2Ftap-tan?logo=homebrew)](https://github.com/steipete/homebrew-tap)\n $\"Ask$ \n\n> 🎉 **NEW in v3**: Complete GUI automation framework with AI Agent! Click, type, scroll, and automate any macOS application using natural language. Plus comprehensive menu bar extraction without clicking! See the [GUI Automation section](#-gui-automation-with-peekaboo-v3) and [AI Agent section](#-ai-agent-automation) for details.\n\nPeekaboo is a powerful macOS utility for capturing screenshots, analyzing them with AI vision models, and now automating GUI interactions. It works both as a **standalone CLI tool** (recommended) and as an **MCP server** for AI assistants like Claude Desktop and Cursor.\n\n## 🎯 Choose Your Path\n\n### 🖥️ **CLI Tool** (Recommended for Most Users)\nPerfect for:\n- Command-line workflows and automation\n- Shell scripts and CI/CD pipelines \n- Quick screenshots and AI analysis\n- System administration tasks\n\n### 👻 **MCP Server** (For AI Assistants)\nPerfect for:\n- Claude Desktop integration\n- Cursor IDE workflows\n- AI agents that need visual context\n- Interactive AI debugging sessions\n\n## What is Peekaboo?\n\nPeekaboo bridges the gap between visual content on your screen and AI understanding. It provides:\n\n- **Lightning-fast screenshots** of screens, applications, or specific windows\n- **AI-powered image analysis** using GPT-4.1 Vision, Claude, Grok, or local models (Ollama)\n- **Complete GUI automation** (v3) - Click, type, scroll, and interact with any macOS app\n- **Natural language automation** (v3) - AI agent that understands tasks like \"Open TextEdit and write a poem\"\n- **Smart UI element detection** - Automatically identifies buttons, text fields, links, and more with precise coordinate mapping\n- **Menu bar extraction** (v3) - Discover all menus and keyboard shortcuts without clicking or opening menus\n- **Automatic session resolution** - Commands intelligently use the most recent session (no manual tracking!)\n- **Window and application management** with smart fuzzy matching\n- **Multi-screen support** - List which screen windows are on and move them between displays\n- **Privacy-first operation** with local AI options via Ollama\n- **Non-intrusive capture** without changing window focus\n- **Automation scripting** - Chain commands together for complex workflows\n\n### 🏗️ Architecture\n\nPeekaboo now composes three focused SwiftPM targets plus a thin umbrella:\n\n- **PeekabooAutomation** – Screen capture, permissions, accessibility services, menu/window helpers, and every strongly typed model shared across apps.\n- **PeekabooAgentRuntime** – Tool registry, MCP server tooling, streaming/agent glue. Nothing here touches AppKit directly; it consumes the automation protocols.\n- **PeekabooVisualizer** – Event serialization and UI feedback for the macOS app + CLI visual overlays.\n- **PeekabooCore** – `_exported` shim that re-exports the three modules so downstream targets can continue to `import PeekabooCore` while opting into narrower modules when desired.\n- **CLI** – Command-line interface that injects a `PeekabooServices()` instance into commander commands and agents.\n- **Mac App** – Native macOS GUI that keeps a long-lived `@State private var services = PeekabooServices()` and passes it through SwiftUI scenes.\n- **MCP Server** – Model Context Protocol server for AI assistants (Claude Desktop, Cursor, etc.) built entirely on `PeekabooAgentRuntime`.\n- **Commander** (in-repo) – Lightweight Swift 6 parsing helpers used by the CLI runtime (swift-tools-version 6.0, no Swift 6.2+ features).\n\nThe CLI command structs remain `@MainActor` so they run on the main thread, but the static `commandDescription` can just be a normal `static let` constant—no `nonisolated(unsafe)` or extra `@MainActor` wrappers are necessary when describing the command metadata.\n\nAll components share the same core services, ensuring consistent behavior and optimal performance. See [Service API Reference](docs/service-api-reference.md) for detailed documentation.\n\n#### Embedding Peekaboo services\n\nThe legacy singleton is gone—if you construct `PeekabooServices()` yourself (e.g., tests, daemon, or a new host), call `services.installAgentRuntimeDefaults()` **once** after initialization so MCP tools, the ToolRegistry, and `PeekabooAgentService` share that instance:\n\n```swift\n@MainActor\nlet services = PeekabooServices()\nservices.installAgentRuntimeDefaults()\n\nlet agent = try PeekabooAgentService(services: services)\n```\n\nSkipping the install step will cause MCP/ToolRegistry APIs to fatal with “default factory not configured” because there’s no hidden global anymore.\n\n### Git Submodules\n\nPeekaboo vendors three shared dependencies as top-level git submodules:\n\n| Path | Purpose |\n|-------------|---------------------------------------|\n| `AXorcist/` | Accessibility automation primitives |\n| `Commander/`| Swift command parser used by the CLI |\n| `Tachikoma/`| AI provider + MCP integrations |\n\nClone with `git clone --recursive` or run `git submodule update --init --recursive` after pulling to ensure all three are present.\n\n#### Submodule Details (updated)\n- `AXorcist` is our accessibility engine: it wraps the macOS AX APIs with type-safe Swift helpers so every command (and agent) can discover UI elements, grant permissions, and drive buttons/text fields without reinventing accessibility plumbing. Because the underlying APIs are macOS-only we keep AXorcist’s CI and release targets scoped to macOS 14+.\n- `Commander` is the shared parser/runtime that replaces Swift Argument Parser across Peekaboo. It provides property-wrapper metadata, a central router, standard CLI flags, and binders that hydrate existing command structs while keeping the runtime @MainActor-friendly. Commander’s CI spans macOS, Linux, Apple simulators (iOS/tvOS/watchOS/visionOS), and Android (via `--swift-sdk android`).\n- `Tachikoma` is the AI provider SDK plus MCP adapters. It now owns all credential/OAuth handling via `TKAuthManager` and exposes the standalone `tk-config` CLI (add/login/status) so hosts can reuse the same auth + validation flows. Peekaboo’s CLI delegates provider auth to Tachikoma; set `TachikomaConfiguration.profileDirectoryName` to `.peekaboo` to share credentials.\n\n## 🧩 Platform Support\n\n| Component | Supported OS targets | Notes |\n| --- | --- | --- |\n| Peekaboo CLI + Mac app | macOS 14.0+ | Everything ships as a native macOS product; CI only runs on macOS runners so we can exercise ScreenCaptureKit and Accessibility APIs. |\n| AXorcist | macOS 14.0+ | Accessibility frameworks are macOS-only, so both the library and its CLI stay scoped to macOS. |\n| Commander | macOS, Linux, Apple simulators (iOS/tvOS/watchOS/visionOS), Android (aarch64) | CI installs Swift toolchains via Swiftly, runs `xcodebuild` against each simulator platform, and cross-compiles with `--swift-sdk android` so Commander stays portable on the platforms we actively test. |\n| Tachikoma | macOS, Linux, Apple simulators (iOS/tvOS/watchOS/visionOS), Android (aarch64) | Matches Commander’s matrix and additionally runs the Android cross-compilation plus the Apple destination builds for provider SDK validation. |\n\n## 🚀 Quick Start: CLI Tool\n\n### Installation\n\n```bash\n# Option 1: Homebrew (Recommended)\nbrew tap steipete/tap\nbrew install peekaboo\n\n# Option 2: Direct Download\ncurl -L https://github.com/steipete/peekaboo/releases/latest/download/peekaboo-macos-universal.tar.gz | tar xz\nsudo mv peekaboo-macos-universal/peekaboo /usr/local/bin/\n\n# Option 3: npm (includes MCP server)\nnpm install -g @steipete/peekaboo-mcp\n\n# Option 4: Build from source\ngit clone https://github.com/steipete/peekaboo.git\ncd peekaboo\n./scripts/build-cli-standalone.sh --install\n```\n\n### Command Catalog\n\nPeekaboo ships many focused commands. Each entry below links to a short doc in `docs/commands/` with complete flag tables, workflows, and troubleshooting notes.\n\n#### Vision & Capture\n- [`see`](docs/commands/see.md) – Capture annotated UI maps, produce session IDs, and optionally run inline analysis.\n- [`image`](docs/commands/image.md) – Grab raw PNG/JPG screenshots (screens, windows, menu bar) and feed them into AI with `--analyze`.\n\n#### Core Utilities\n- [`list`](docs/commands/list.md) – Subcommands: `apps`, `windows`, `screens`, `menubar`, `permissions`.\n- [`tools`](docs/commands/tools.md) – Enumerate native + MCP tools; filter by server/source.\n- [`config`](docs/commands/config.md) – Subcommands: `init`, `show` (live validation), `add [--timeout]`, `login ` (OpenAI/Codex, Anthropic Max OAuth), legacy `set-credential`, `models`.\n- [`permissions`](docs/commands/permissions.md) – `status` (default) and `grant` helpers for Screen Recording, Accessibility, etc.\n- [`learn`](docs/commands/learn.md) – Emit the full agent guide/system prompt/Commander signature dump.\n- [`run`](docs/commands/run.md) – Execute `.peekaboo.json` automation scripts (`--output`, `--no-fail-fast`).\n- [`sleep`](docs/commands/sleep.md) – Millisecond delays between scripted steps.\n- [`clean`](docs/commands/clean.md) – Prune session caches via `--all-sessions`, `--older-than`, or `--session`.\n\n#### Interaction\n- [`click`](docs/commands/click.md) – Element IDs, fuzzy queries, or coordinates; built-in wait/focus helpers.\n- [`type`](docs/commands/type.md) – Text + escape sequences, `--clear`, tab/return/escape/delete flags.\n- [`press`](docs/commands/press.md) – Special key sequences with repeat counts.\n- [`hotkey`](docs/commands/hotkey.md) – Modifier combos such as `cmd,shift,t` (terminal-safe parsing).\n- [`scroll`](docs/commands/scroll.md) – Directional scrolls with optional element targets.\n- [`swipe`](docs/commands/swipe.md) – Smooth drags between IDs or coordinates (`--duration`, `--steps`).\n- [`drag`](docs/commands/drag.md) – Drag-and-drop, modifiers, Dock/Trash targets.\n- [`move`](docs/commands/move.md) – Cursor placement (coords, element IDs, queries, or screen center).\n\n#### Windows, Menus, Apps, Spaces\n- [`window`](docs/commands/window.md) – Subcommands: `close`, `minimize`, `maximize`, `move`, `resize`, `set-bounds`, `focus`, `list`.\n- [`menu`](docs/commands/menu.md) – `click`, `click-extra`, `list`, `list-all` for app menus and menu extras.\n- [`menubar`](docs/commands/menubar.md) – `list`/`click` status-bar items by name or index.\n- [`app`](docs/commands/app.md) – `launch`, `quit`, `relaunch`, `hide`, `unhide`, `switch`, `list`.\n- [`open`](docs/commands/open.md) – macOS-style `open` with Peekaboo focus/failure handling.\n- [`dock`](docs/commands/dock.md) – `launch`, `right-click`, `hide`, `show`, `list` for Dock entries.\n- [`dialog`](docs/commands/dialog.md) – `click`, `input`, `file`, `dismiss`, `list` system dialogs.\n- [`space`](docs/commands/space.md) – `list`, `switch`, `move-window` (Spaces/virtual desktops).\n\n#### Agents & Integrations\n- [`agent`](docs/commands/agent.md) – Natural-language automation (`--dry-run`, `--resume`, `--model`, audio options, session caching).\n- [`mcp`](docs/commands/mcp.md) – `serve`, `list`, `add`, `remove`, `enable`, `disable`, `info`, `test`, `call`, `inspect` (stub) for Model Context Protocol workflows.\n\nEach doc contains exhaustive flag descriptions and examples; the README only covers intent and grouping. Use `peekaboo --help` for inline summaries.\n\n### Debugging with Verbose Mode\n\nAll Peekaboo commands support the `--verbose` or `-v` flag for detailed logging:\n\n```bash\n# See what's happening under the hood\npeekaboo image --app Safari --verbose\npeekaboo see --app Terminal -v\npeekaboo click --on B1 --verbose\n\n# Verbose output includes:\n# - Application search details\n# - Window discovery information\n# - UI element detection progress\n# - Timing information\n# - Session management operations\n```\n\nVerbose logs are written to stderr with timestamps:\n```\n[2025-01-06T08:05:23Z] VERBOSE: Searching for application: Safari\n[2025-01-06T08:05:23Z] VERBOSE: Found exact bundle ID match: Safari\n[2025-01-06T08:05:23Z] VERBOSE: Capturing window for app: Safari\n[2025-01-06T08:05:23Z] VERBOSE: Found 3 windows for application\n```\n\nThis is invaluable for:\n- Debugging automation scripts\n- Understanding why elements aren't found\n- Performance optimization\n- Learning Peekaboo's internals\n\n### Configuration\n\nPeekaboo uses a unified configuration directory at `~/.peekaboo/` for better discoverability:\n\n```bash\n# Create default configuration\npeekaboo config init\n\n# Files created:\n# ~/.peekaboo/config.json - Main configuration (JSONC format)\n# ~/.peekaboo/credentials - API keys (chmod 600)\n```\n\n#### Managing API Keys Securely\n\n```bash\n# Set API key securely (stored in ~/.peekaboo/credentials)\npeekaboo config set-credential OPENAI_API_KEY sk-...\n\n# View current configuration (keys shown as ***SET***)\npeekaboo config show --effective\n```\n\n#### Example Configuration\n\n`~/.peekaboo/config.json`:\n```json\n{\n // AI Provider Settings\n \"aiProviders\": {\n \"providers\": \"openai/gpt-4.1,anthropic/claude-opus-4,grok/grok-4,ollama/llava:latest\",\n // NOTE: API keys should be in ~/.peekaboo/credentials\n \"ollamaBaseUrl\": \"http://localhost:11434\"\n },\n \n // Default Settings\n \"defaults\": {\n \"savePath\": \"~/Desktop/Screenshots\",\n \"imageFormat\": \"png\",\n \"captureMode\": \"window\",\n \"captureFocus\": \"auto\"\n },\n \n // Logging\n \"logging\": {\n \"level\": \"info\",\n \"path\": \"~/.peekaboo/logs/peekaboo.log\"\n }\n}\n```\n\n`~/.peekaboo/credentials` (auto-created with proper permissions):\n```\n# Peekaboo credentials file\n# This file contains sensitive API keys and should not be shared\nOPENAI_API_KEY=sk-...\nANTHROPIC_API_KEY=sk-ant-...\nX_AI_API_KEY=xai-...\n```\n\n### Common Workflows\n\n```bash\n# Capture and analyze in one command\npeekaboo image --app Safari --analyze \"What's on this page?\" --path /tmp/page.png\n\n# Monitor active window changes\nwhile true; do\n peekaboo image --mode frontmost --json-output | jq -r '.data.saved_files[0].window_title'\n sleep 5\ndone\n\n# Batch analyze screenshots\nfor img in ~/Screenshots/*.png; do\n peekaboo image --analyze \"Summarize this screenshot\" --path \"$img\"\ndone\n\n# Automated login workflow (v3 with automatic session resolution)\npeekaboo see --app MyApp # Creates new session\npeekaboo click --on T1 # Automatically uses session from 'see'\npeekaboo type \"user@example.com\" # Still using same session\npeekaboo press tab # Press Tab to move to next field\npeekaboo type \"password123\"\npeekaboo press return # Press Enter to submit\npeekaboo sleep 2000 # Wait 2 seconds\n\n# Multiple app automation with explicit sessions\nSESSION_A=$(peekaboo see --app Safari --json-output | jq -r '.data.session_id')\nSESSION_B=$(peekaboo see --app Notes --json-output | jq -r '.data.session_id')\npeekaboo click --on B1 --session $SESSION_A # Click in Safari\npeekaboo type \"Hello\" --session $SESSION_B # Type in Notes\n\n# Run automation script\npeekaboo run login.peekaboo.json\n```\n\n## 👻 MCP Server Setup\n\nFor AI assistants like Claude Desktop and Cursor, Peekaboo provides a Model Context Protocol (MCP) server.\n\n### For Claude Desktop\n\n1. Open Claude Desktop Settings (from the **menubar**, not the in-app settings)\n2. Navigate to Developer → Edit Config\n3. Add the Peekaboo MCP server configuration:\n\n```json\n{\n \"mcpServers\": {\n \"peekaboo\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@steipete/peekaboo-mcp@beta\"],\n \"env\": {\n \"PEEKABOO_AI_PROVIDERS\": \"anthropic/claude-opus-4,openai/gpt-4.1,ollama/llava:latest\",\n \"OPENAI_API_KEY\": \"your-openai-api-key-here\"\n }\n }\n }\n}\n```\n\n4. Save and restart Claude Desktop\n\n### For Claude Code\n\nRun the following command:\n\n```bash\nclaude mcp add-json peekaboo '{\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@steipete/peekaboo-mcp\"],\n \"env\": {\n \"PEEKABOO_AI_PROVIDERS\": \"anthropic/claude-opus-4,openai/gpt-4.1,ollama/llava:latest\",\n \"OPENAI_API_KEY\": \"your-openai-api-key-here\"\n }\n}'\n```\n\nAlternatively, if you've already installed the server via Claude Desktop, you can import it:\n\n```bash\nclaude mcp add-from-claude-desktop\n```\n\n### Local Development\n\nFor local development, use the built MCP server directly:\n\n```json\n{\n \"mcpServers\": {\n \"peekaboo\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/peekaboo/Server/dist/index.js\"],\n \"env\": {\n \"PEEKABOO_AI_PROVIDERS\": \"anthropic/claude-opus-4\"\n }\n }\n }\n}\n```\n\n### For Cursor IDE\n\nAdd to your Cursor settings:\n\n```json\n{\n \"mcpServers\": {\n \"peekaboo\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@steipete/peekaboo-mcp@beta\"],\n \"env\": {\n \"PEEKABOO_AI_PROVIDERS\": \"openai/gpt-4.1,ollama/llava:latest\",\n \"OPENAI_API_KEY\": \"your-openai-api-key-here\"\n }\n }\n }\n}\n```\n\n## 🔗 MCP Client Integration\n\nPeekaboo v3 now functions as both an MCP server (exposing its tools) and an MCP client (consuming external tools). This enables powerful workflows that combine Peekaboo's native automation with tools from the broader MCP ecosystem.\n\n### Default Integration: Chrome DevTools MCP\n\nPeekaboo ships with the [Chrome DevTools MCP](https://chrome-devtools-mcp.modelcontextprotocol.io) enabled by default, providing Chromium automation via the DevTools protocol:\n\n```bash\n# Chrome DevTools tools are available immediately\npeekaboo tools --mcp-only # List only external MCP tools \npeekaboo tools --mcp chrome-devtools # Show Chrome DevTools MCP tools specifically\npeekaboo agent \"Navigate to github.com and click the sign up button\" # Uses chrome-devtools:navigate_page + click\n```\n\n### Managing External MCP Servers\n\n```bash\n# List all configured servers with health status\npeekaboo mcp list\n\n# Add popular MCP servers\npeekaboo mcp add github -e GITHUB_TOKEN=ghp_xxx -- npx -y @modelcontextprotocol/server-github\npeekaboo mcp add files -- npx -y @modelcontextprotocol/server-filesystem ~/Documents\n\n# Test server connection\npeekaboo mcp test github --show-tools\n\n# Enable/disable servers\npeekaboo mcp disable chrome-devtools # Disable default Chrome DevTools MCP\npeekaboo mcp enable github # Re-enable a server\n```\n\n### Configuration\n\nExternal servers are configured in `~/.peekaboo/config.json`. To disable Chrome DevTools MCP:\n\n```json\n{\n \"mcpClients\": {\n \"chrome-devtools\": {\n \"enabled\": false\n }\n }\n}\n```\n\n### Available External Tools\n\nAll external tools are prefixed with their server name:\n\n- **chrome-devtools:navigate_page** - Navigate to URL (Chrome DevTools MCP)\n- **chrome-devtools:click** - Click elements on webpage (Chrome DevTools MCP) \n- **chrome-devtools:screenshot** - Take webpage screenshot (Chrome DevTools MCP)\n- **github:create_issue** - Create GitHub issues (GitHub server)\n- **files:read_file** - Read files (Filesystem server)\n\nThe AI agent automatically uses the best combination of native and external tools for each task.\n\nSee [docs/mcp-client.md](docs/mcp-client.md) for complete documentation.\n\n### MCP Tools Available\n\n#### Core Tools\n1. **`image`** - Capture screenshots (with optional AI analysis via question parameter)\n2. **`list`** - List applications, windows, or check server status\n3. **`analyze`** - Analyze existing images with AI vision models (MCP-only tool, use `peekaboo image --analyze` in CLI)\n\n#### UI Automation Tools\n4. **`see`** - Capture screen and identify UI elements\n5. **`click`** - Click on UI elements or coordinates\n6. **`type`** - Type text into UI elements (supports escape sequences)\n7. **`press`** - Press individual keys (return, tab, escape, arrows, etc.)\n8. **`scroll`** - Scroll content in any direction\n9. **`hotkey`** - Press keyboard shortcuts\n10. **`swipe`** - Perform swipe/drag gestures\n11. **`move`** - Move mouse cursor to specific position or element\n12. **`drag`** - Perform drag and drop operations\n\n#### Application & Window Management\n13. **`app`** - Launch, quit, focus, hide, and manage applications\n14. **`window`** - Manipulate windows (close, minimize, maximize, move, resize, focus)\n15. **`menu`** - Interact with application menus and system menu extras\n16. **`dock`** - Launch apps from dock and manage dock items\n17. **`dialog`** - Handle dialog windows (click buttons, input text)\n18. **`space`** - Manage macOS Spaces (virtual desktops)\n\n#### Utility Tools\n19. **`run`** - Execute automation scripts from .peekaboo.json files\n20. **`sleep`** - Pause execution for specified duration\n21. **`clean`** - Clean up session cache and temporary files\n22. **`permissions`** - Check system permissions (screen recording, accessibility)\n23. **`agent`** - Execute complex automation tasks using AI\n\n## 📟 CLI Command Reference\n\nFull command descriptions now live in [docs/cli-command-reference.md](docs/cli-command-reference.md).\n\n## 🚀 GUI Automation with Peekaboo v3\n\nPeekaboo v3 introduces powerful GUI automation capabilities, transforming it from a screenshot tool into a complete UI automation framework for macOS. This enables AI assistants to interact with any application through natural language commands.\n\n### How It Works\n\nThe v3 automation system uses a **see-then-interact** workflow:\n\n1. **See** - Capture the screen and identify UI elements\n2. **Interact** - Click, type, scroll, or perform other actions\n3. **Verify** - Capture again to confirm the action succeeded\n\n### 🎯 The `see` Tool - UI Element Discovery\n\nThe `see` tool is the foundation of GUI automation. It captures a screenshot and identifies all interactive UI elements, assigning them unique Peekaboo IDs.\n\n```typescript\n// Example: See what's on screen\nawait see({ app_target: \"Safari\" })\n\n// Multi-screen support - capture all screens\nawait see({ app_target: \"\" }) // Empty string captures all screens\n\n// Capture specific screen by index\nawait see({ app_target: \"screen:0\" }) // Primary screen\nawait see({ app_target: \"screen:1\" }) // Second screen\n\n// Returns:\n{\n screenshot_path: \"/tmp/peekaboo_123.png\",\n session_id: \"session_456\",\n elements: {\n buttons: [\n { id: \"B1\", label: \"Submit\", bounds: { x: 100, y: 200, width: 80, height: 30 } },\n { id: \"B2\", label: \"Cancel\", bounds: { x: 200, y: 200, width: 80, height: 30 } }\n ],\n text_fields: [\n { id: \"T1\", label: \"Email\", value: \"\", bounds: { x: 100, y: 100, width: 200, height: 30 } },\n { id: \"T2\", label: \"Password\", value: \"\", bounds: { x: 100, y: 150, width: 200, height: 30 } }\n ],\n links: [\n { id: \"L1\", label: \"Forgot password?\", bounds: { x: 100, y: 250, width: 120, height: 20 } }\n ],\n // ... other elements\n }\n}\n```\n\n#### Discovering Available Screens\n\nBefore capturing specific screens, you can list all connected displays:\n\n```bash\n# List all screens with details\npeekaboo list screens\n\n# Example output:\n# Screens (3 total):\n# \n# 0. Built-in Display (Primary)\n# Resolution: 3008×1692\n# Position: 0,0\n# Scale: 2.0x (Retina)\n# Visible Area: 3008×1612\n# \n# 1. External Display\n# Resolution: 3840×2160\n# Position: 3008,0\n# Scale: 2.0x (Retina)\n# \n# 2. Studio Display\n# Resolution: 5120×2880\n# Position: -5120,0\n# Scale: 2.0x (Retina)\n# \n# 💡 Use 'peekaboo see --screen-index N' to capture a specific screen\n\n# Get JSON output for scripting\npeekaboo list screens --json-output\n```\n\nThis command shows:\n- **Screen index**: Use with `see --screen-index` or `image --screen-index`\n- **Display name**: Built-in, External, or specific model names\n- **Resolution**: Full screen resolution\n- **Position**: Coordinates in the unified desktop space\n- **Scale factor**: Retina display information\n- **Visible area**: Usable area (excluding menu bar on primary screen)\n\n#### Multi-Screen Capture\nWhen capturing multiple screens, Peekaboo automatically saves each screen as a separate file:\n- Primary screen: `screenshot.png`\n- Additional screens: `screenshot_screen1.png`, `screenshot_screen2.png`, etc.\n\nDisplay information (name, resolution) is shown for each captured screen:\n```\n📸 Captured 3 screens:\n 🖥️ Display 0: Built-in Retina Display (2880×1800) → screenshot.png\n 🖥️ Display 1: LG Ultra HD (3840×2160) → screenshot_screen1.png\n 🖥️ Display 2: Studio Display (5120×2880) → screenshot_screen2.png\n```\n\n**Note**: Annotation is automatically disabled for full screen captures due to performance constraints.\n\n#### Element ID Format\n- **B1, B2...** - Buttons\n- **T1, T2...** - Text fields/areas\n- **L1, L2...** - Links\n- **G1, G2...** - Groups/containers\n- **I1, I2...** - Images\n- **S1, S2...** - Sliders\n- **C1, C2...** - Checkboxes/toggles\n- **M1, M2...** - Menu items\n\n### 🖱️ The `click` Tool\n\nClick on UI elements using various targeting methods:\n\n```typescript\n// Click by element ID from see command\nawait click({ on: \"B1\" })\n\n// Click by query (searches button labels)\nawait click({ query: \"Submit\" })\n\n// Click by coordinates\nawait click({ coords: \"450,300\" })\n\n// Double-click\nawait click({ on: \"I1\", double: true })\n\n// Right-click\nawait click({ query: \"File\", right: true })\n\n// With custom wait timeout\nawait click({ query: \"Save\", wait_for: 10000 })\n```\n\n### ⌨️ The `type` Tool\n\nType text with support for escape sequences:\n\n```typescript\n// Type into a specific field\nawait type({ text: \"user@example.com\", on: \"T1\" })\n\n// Type at current focus\nawait type({ text: \"Hello world\" })\n\n// Clear existing text first\nawait type({ text: \"New text\", on: \"T2\", clear: true })\n\n// Use escape sequences\nawait type({ text: \"Line 1\\nLine 2\\nLine 3\" }) // Newlines\nawait type({ text: \"Name:\\tJohn\\tDoe\" }) // Tabs\nawait type({ text: \"Path: C:\\\\data\\\\file.txt\" }) // Literal backslash\n\n// Press return after typing\nawait type({ text: \"Submit\", press_return: true })\n\n// Adjust typing speed\nawait type({ text: \"Slow typing\", delay: 100 })\n```\n\n#### Supported Escape Sequences\n- `\\n` - Newline/return\n- `\\t` - Tab\n- `\\b` - Backspace/delete\n- `\\e` - Escape\n- `\\\\` - Literal backslash\n\n### 🔑 The `press` Tool\n\nPress individual keys or key sequences:\n\n```typescript\n// Press single keys\nawait press({ key: \"return\" }) // Press Enter\nawait press({ key: \"tab\", count: 3 }) // Press Tab 3 times\nawait press({ key: \"escape\" }) // Press Escape\n\n// Navigation keys\nawait press({ key: \"up\" }) // Arrow up\nawait press({ key: \"down\", count: 5 }) // Arrow down 5 times\nawait press({ key: \"home\" }) // Home key\nawait press({ key: \"end\" }) // End key\n\n// Function keys\nawait press({ key: \"f1\" }) // F1 help key\nawait press({ key: \"f11\" }) // F11 full screen\n\n// Special keys\nawait press({ key: \"forward_delete\" }) // Forward delete (fn+delete)\nawait press({ key: \"caps_lock\" }) // Caps Lock\n```\n\n#### Available Keys\n- **Navigation**: up, down, left, right, home, end, pageup, pagedown\n- **Editing**: delete (backspace), forward_delete, clear\n- **Control**: return, enter, tab, escape, space\n- **Function**: f1-f12\n- **Special**: caps_lock, help\n\n### 📜 The `scroll` Tool\n\nScroll content in any direction:\n\n```typescript\n// Scroll down 3 ticks (default)\nawait scroll({ direction: \"down\" })\n\n// Scroll up 5 ticks\nawait scroll({ direction: \"up\", amount: 5 })\n\n// Scroll on a specific element\nawait scroll({ direction: \"down\", on: \"G1\", amount: 10 })\n\n// Smooth scrolling\nawait scroll({ direction: \"down\", smooth: true })\n\n// Horizontal scrolling\nawait scroll({ direction: \"right\", amount: 3 })\n```\n\n### ⌨️ The `hotkey` Tool\n\nPress keyboard shortcuts:\n\n```typescript\n// Common shortcuts\nawait hotkey({ keys: \"cmd,c\" }) // Copy\nawait hotkey({ keys: \"cmd,v\" }) // Paste\nawait hotkey({ keys: \"cmd,tab\" }) // Switch apps\nawait hotkey({ keys: \"cmd,shift,t\" }) // Reopen closed tab\n\n// Function keys\nawait hotkey({ keys: \"f11\" }) // Full screen\n\n// Custom hold duration\nawait hotkey({ keys: \"cmd,space\", hold_duration: 100 })\n```\n\n### 👆 The `swipe` Tool\n\nPerform swipe or drag gestures:\n\n```typescript\n// Basic swipe\nawait swipe({ from: \"100,200\", to: \"300,200\" })\n\n// Slow drag\nawait swipe({ from: \"50,50\", to: \"200,200\", duration: 2000 })\n\n// Precise movement with more steps\nawait swipe({ from: \"0,0\", to: \"100,100\", steps: 50 })\n```\n\n### 🖱️ The `move` Tool\n\nMove the mouse cursor to specific positions or UI elements:\n\n```typescript\n// Move to absolute coordinates\nawait move({ coordinates: \"500,300\" })\n\n// Move to center of screen\nawait move({ center: true })\n\n// Move to a specific UI element\nawait move({ id: \"B1\" })\n\n// Smooth movement with animation\nawait move({ coordinates: \"100,200\", smooth: true, duration: 1000 })\n```\n\n### 🎯 The `drag` Tool\n\nPerform drag and drop operations between UI elements or coordinates:\n\n```typescript\n// Drag from one element to another\nawait drag({ from: \"B1\", to: \"T1\" })\n\n// Drag using coordinates\nawait drag({ from_coords: \"100,100\", to_coords: \"500,500\" })\n\n// Drag with modifiers (e.g., holding shift)\nawait drag({ from: \"I1\", to: \"G2\", modifiers: \"shift\" })\n\n// Cross-application drag\nawait drag({ from: \"T1\", to_app: \"Finder\", to_coords: \"300,400\" })\n```\n\n### 🔐 The `permissions` Tool\n\nCheck macOS system permissions required for automation:\n\n```typescript\n// Check all permissions\nawait permissions({})\n\n// Returns permission status for:\n// - Screen Recording (required for screenshots)\n// - Accessibility (required for UI automation)\n```\n\n### 📝 The `run` Tool - Automation Scripts\n\nExecute complex automation workflows from JSON script files:\n\n```typescript\n// Run a script\nawait run({ script_path: \"/path/to/login.peekaboo.json\" })\n\n// Continue on error\nawait run({ script_path: \"test.peekaboo.json\", no_fail_fast: true })\n```\n\n#### Script Format (.peekaboo.json)\n\n```json\n{\n \"name\": \"Login to Website\",\n \"description\": \"Automated login workflow\",\n \"commands\": [\n {\n \"command\": \"see\",\n \"args\": { \"app_target\": \"Safari\" },\n \"comment\": \"Capture current state\"\n },\n {\n \"command\": \"click\",\n \"args\": { \"query\": \"Email\" },\n \"comment\": \"Click email field\"\n },\n {\n \"command\": \"type\",\n \"args\": { \"text\": \"user@example.com\" }\n },\n {\n \"command\": \"click\",\n \"args\": { \"query\": \"Password\" }\n },\n {\n \"command\": \"type\",\n \"args\": { \"text\": \"secure_password\" }\n },\n {\n \"command\": \"click\",\n \"args\": { \"query\": \"Sign In\" }\n },\n {\n \"command\": \"sleep\",\n \"args\": { \"duration\": 2000 },\n \"comment\": \"Wait for login\"\n }\n ]\n}\n```\n\n### 🎯 Automatic Window Focus Management\n\nPeekaboo v3 includes intelligent window focus management that ensures your automation commands target the correct window, even across different macOS Spaces (virtual desktops).\n\n#### How Focus Management Works\n\nAll interaction commands (`click`, `type`, `scroll`, `menu`, `hotkey`, `drag`) automatically:\n1. **Track window identity** - Using stable window IDs that persist across interactions\n2. **Detect window location** - Find which Space contains the target window\n3. **Switch Spaces if needed** - Automatically switch to the window's Space\n4. **Focus the window** - Ensure the window is frontmost before interaction\n5. **Verify focus** - Confirm the window is ready before proceeding\n\n#### Focus Options\n\nAll interaction commands support these focus-related flags:\n\n```bash\n# Disable automatic focus (not recommended)\npeekaboo click \"Submit\" --no-auto-focus\n\n# Set custom focus timeout (default: 5 seconds)\npeekaboo type \"Hello\" --focus-timeout 10\n\n# Set retry count for focus operations (default: 3)\npeekaboo menu click --app Safari --item \"New Tab\" --focus-retry-count 5\n\n# Control Space switching behavior\npeekaboo click \"Login\" --space-switch # Force Space switch\npeekaboo type \"text\" --bring-to-current-space # Move window to current Space\n```\n\n#### Space Management Commands\n\nPeekaboo provides dedicated commands for managing macOS Spaces:\n\n```bash\n# List all Spaces\npeekaboo space list\n\n# Switch to a specific Space\npeekaboo space switch --to 2\n\n# Move windows between Spaces\npeekaboo space move-window --app Safari --to 3\n\n# Use list to see which Space contains windows\npeekaboo space list # Shows all Spaces and their windows\n```\n\n#### Window Focus Command\n\nFor explicit window focus control:\n\n```bash\n# Focus a window (switches Space if needed)\npeekaboo window focus --app Safari\n\n# Focus without switching Spaces (space-switch is a flag, not an option with value)\npeekaboo window focus --app Terminal # Default is to not switch spaces unless needed\n\n# Move window to current Space and focus\npeekaboo window focus --app \"VS Code\" --bring-to-current-space\n```\n\n#### Focus Behavior\n\nBy default, Peekaboo:\n- **Automatically focuses windows** before any interaction\n- **Switches Spaces** when the target window is on a different desktop\n- **Waits for focus** to ensure the window is ready\n- **Retries if needed** with exponential backoff\n\nThis ensures reliable automation across complex multi-window, multi-Space workflows without manual window management.\n\n## 👻 AI Agent Automation\n\nPeekaboo v3 introduces an AI-powered agent that can understand and execute complex automation tasks using natural language. The agent uses OpenAI's Chat Completions API with streaming support to break down your instructions into specific Peekaboo commands.\n\n### Setting Up the Agent\n\n```bash\n# Set your API key (OpenAI, Anthropic, or Grok)\nexport OPENAI_API_KEY=\"your-openai-key-here\"\n# OR\nexport ANTHROPIC_API_KEY=\"your-anthropic-key-here\"\n# OR\nexport X_AI_API_KEY=\"your-grok-key-here\"\n\n# Or save it securely in Peekaboo's config\npeekaboo config set-credential OPENAI_API_KEY your-api-key-here\npeekaboo config set-credential ANTHROPIC_API_KEY your-anthropic-key-here\npeekaboo config set-credential X_AI_API_KEY your-grok-key-here\n\n# Now you can use natural language automation!\npeekaboo \"Open Safari and search for weather\"\npeekaboo agent \"Fill out the form\" --model grok-4-fast-reasoning\npeekaboo agent \"Create a document\" --model claude-opus-4\n```\n\n### Two Ways to Use the Agent\n\n#### 1. Direct Natural Language (Default)\nWhen you provide a text argument without a subcommand, Peekaboo automatically uses the agent:\n\n```bash\n# These all invoke the agent directly\npeekaboo \"Click the Submit button\"\npeekaboo \"Open TextEdit and write Hello\"\npeekaboo \"Take a screenshot of Safari\"\n```\n\n#### 2. Explicit Agent Command\nUse the `agent` subcommand for more control and options:\n\n```bash\n# With options and flags\npeekaboo agent \"Fill out the contact form\" --verbose\npeekaboo agent \"Close all Finder windows\" --dry-run\npeekaboo agent \"Install this app\" --max-steps 30 --json-output\n```\n\n### How the Agent Works\n\n1. **Understands Your Intent** - The AI agent analyzes your natural language request\n2. **Plans the Steps** - Breaks down the task into specific actions\n3. **Executes Commands** - Uses Peekaboo's automation tools to perform each step\n4. **Verifies Results** - Takes screenshots to confirm actions succeeded\n5. **Handles Errors** - Can retry failed actions or adjust approach\n\n### Real-World Examples\n\n```bash\n# Web Automation\npeekaboo \"Go to github.com and search for peekaboo\"\npeekaboo \"Click the first search result\"\npeekaboo \"Star this repository\"\n\n# Document Creation\npeekaboo \"Open Pages and create a new blank document\"\npeekaboo \"Type 'Meeting Agenda' as the title and make it bold\"\npeekaboo \"Add bullet points for Introduction, Main Topics, and Action Items\"\n\n# File Management\npeekaboo \"Open Finder and navigate to Downloads\"\npeekaboo \"Select all PDF files and move them to Documents\"\npeekaboo \"Create a new folder called 'Archived PDFs'\"\n\n# Application Testing\npeekaboo \"Launch Calculator and calculate 42 * 17\"\npeekaboo \"Take a screenshot of the result\"\npeekaboo \"Clear the calculator and close it\"\n\n# System Tasks\npeekaboo \"Open System Settings and go to Display settings\"\npeekaboo \"Change the display resolution to 1920x1080\"\npeekaboo \"Take a screenshot to confirm the change\"\n```\n\n### Agent Options\n\n- `--verbose` - See the agent's reasoning and planning process\n- `--dry-run` - Preview what the agent would do without executing\n- `--max-steps ` - Limit the number of actions (default: 20)\n- `--model ` - Choose OpenAI model (default: gpt-4-turbo)\n- `--json-output` - Get structured JSON output\n- `--resume` - Resume the latest unfinished agent session\n- `--resume ` - Resume a specific session by ID\n\n### Agent Capabilities\n\nThe agent has access to all Peekaboo commands:\n- **Visual Understanding** - Can see and understand what's on screen\n- **UI Interaction** - Click buttons, fill forms, navigate menus\n- **Text Entry** - Type text, use keyboard shortcuts\n- **Window Management** - Open, close, minimize, arrange windows\n- **Application Control** - Launch apps, switch between them\n- **File Operations** - Save files, handle dialogs\n- **Complex Workflows** - Chain multiple actions together\n- **Multiple AI Models** - Supports OpenAI (GPT-4o, o3), Anthropic (Claude), and Grok (xAI)\n\n### Understanding Agent Execution\n\nWhen you run an agent command, here's what happens behind the scenes:\n\n```bash\n# Your command:\npeekaboo \"Click the Submit button\"\n\n# Agent breaks it down into:\npeekaboo see # Capture screen and identify elements\npeekaboo click \"Submit\" # Click the identified button\n```\n\n### Example Workflow\n\n```bash\n# Complex multi-step task\npeekaboo agent --verbose \"Create a new document in Pages with the title 'Meeting Notes' and add today's date\"\n\n# Agent will execute commands like:\n# 1. peekaboo see --app Pages # Check if Pages is open\n# 2. peekaboo app launch Pages # Launch if needed\n# 3. peekaboo sleep --duration 2000 # Wait for app to load\n# 4. peekaboo click \"Create Document\" # Click new document\n# 5. peekaboo type \"Meeting Notes\" # Enter title\n# 6. peekaboo hotkey cmd+b # Make text bold\n# 7. peekaboo hotkey return # New line\n# 8. peekaboo type \"Date: $(date)\" # Add current date\n\n# Relaunch an application (useful for applying settings or fixing issues)\npeekaboo app relaunch Safari # Quit and restart Safari\npeekaboo app relaunch \"Visual Studio Code\" --wait 3 --wait-until-ready\n\n# Open URLs or documents via Peekaboo (instead of raw `open`)\npeekaboo open https://example.com --json-output\npeekaboo open ~/Documents/report.pdf --app \"Preview\" --wait-until-ready\n\n# Launch an app and hand it documents/URLs immediately\npeekaboo app launch \"Safari\" \\\n --open https://news.ycombinator.com \\\n --open https://example.com/status \\\n --no-focus\n```\n\n### Debugging Agent Actions\n\nUse `--verbose` to see exactly what the agent is doing:\n\n```bash\npeekaboo agent --verbose \"Find and click the login button\"\n\n# Output will show:\n# [Agent] Analyzing request...\n# [Agent] Planning steps:\n# 1. Capture current screen\n# 2. Identify login button\n# 3. Click on the button\n# [Agent] Executing: peekaboo see\n# [Agent] Found elements: button \"Login\" at (834, 423)\n# [Agent] Executing: peekaboo click \"Login\"\n# [Agent] Action completed successfully\n```\n\n### Tips for Best Results\n\n1. **Be Specific** - \"Click the blue Submit button\" works better than \"submit\"\n2. **One Task at a Time** - Break complex workflows into smaller tasks\n3. **Verify State** - The agent works best when it can see the current screen\n4. **Use Verbose Mode** - Add `--verbose` to understand what the agent is doing\n5. **Set Reasonable Limits** - Use `--max-steps` to prevent runaway automation\n\n### Resuming Agent Sessions\n\nThe agent supports resuming interrupted or incomplete sessions, maintaining full conversation context:\n\n```bash\n# Start a complex task\npeekaboo agent \"Help me write a document about automation\"\n# Agent creates document, starts writing...\n# \n\n# Resume the latest session with context\npeekaboo agent --resume \"Continue where we left off\"\n\n# Or resume a specific session\npeekaboo agent --resume session_abc123 \"Add a conclusion section\"\n\n# List available sessions\npeekaboo agent --list-sessions\n\n# Note: There is no show-session command, use list-sessions to see all sessions\n```\n\n#### How Resume Works\n\n1. **Session Persistence** - Each agent run creates a session with a unique ID\n2. **Thread Continuity** - Uses OpenAI's thread persistence to maintain conversation history\n3. **Context Preservation** - The AI remembers all previous interactions in the session\n4. **Smart Recovery** - Can continue from any point, understanding what was already done\n\n#### Resume Examples\n\n```bash\n# Scenario 1: Continue an interrupted task\npeekaboo agent \"Create a presentation about AI\"\n# \npeekaboo agent --resume \"Add more slides about machine learning\"\n\n# Scenario 2: Iterative refinement\npeekaboo agent \"Fill out this form with test data\"\n# \npeekaboo agent --resume \"Actually, change the email to test@example.com\"\n\n# Scenario 3: Debugging automation\npeekaboo agent --verbose \"Login to the portal\"\n# \npeekaboo agent --resume --verbose \"Try clicking the other login button\"\n```\n\n### ⏸️ The `sleep` Tool\n\nPause execution between actions:\n\n```typescript\n// Sleep for 1 second\nawait sleep({ duration: 1000 })\n\n// Sleep for 500ms\nawait sleep({ duration: 500 })\n```\n\n### 🪟 The `window` Tool\n\nComprehensive window manipulation for any application:\n\n```typescript\n// Close window\nawait window({ action: \"close\", app: \"Safari\" })\nawait window({ action: \"close\", app: \"Safari\", title: \"Downloads\" })\n\n// Minimize/Maximize\nawait window({ action: \"minimize\", app: \"Finder\" })\nawait window({ action: \"maximize\", app: \"Terminal\" })\n\n// Move window\nawait window({ action: \"move\", app: \"TextEdit\", x: 100, y: 100 })\n\n// Resize window\nawait window({ action: \"resize\", app: \"Notes\", width: 800, height: 600 })\n\n// Set exact bounds (move + resize)\nawait window({ action: \"set-bounds\", app: \"Safari\", x: 50, y: 50, width: 1200, height: 800 })\n\n// Focus window\nawait window({ action: \"focus\", app: \"Visual Studio Code\" })\nawait window({ action: \"focus\", app: \"Safari\", index: 0 }) // Focus first window\n\n// List all windows (Note: window tool doesn't have a list action)\n// Use the list tool instead: await list({ item_type: \"application_windows\", app: \"Finder\" })\n```\n\n#### Window Actions\n- **close** - Close the window (animated if has close button)\n- **minimize** - Minimize to dock\n- **maximize** - Maximize/zoom window\n- **move** - Move to specific coordinates\n- **resize** - Change window dimensions\n- **set-bounds** - Set position and size in one operation\n- **focus** - Bring window to front and focus\n\n#### Targeting Options\n- **app** - Target by application name (fuzzy matching supported)\n- **title** - Target by window title (substring matching)\n- **index** - Target by index (0-based, front to back order)\n\n### 🖥️ Multi-Screen Support\n\nPeekaboo v3 includes comprehensive multi-screen support for window management across multiple displays. When listing windows, Peekaboo shows which screen each window is on, and provides powerful options for moving windows between screens.\n\n#### Screen Identification\nWhen listing windows, each window shows its screen location:\n```bash\n# Windows now show their screen in the output\npeekaboo list windows --app Safari\n# Output includes: \"Screen: Built-in Display\" or \"Screen: External Display\"\n```\n\n#### Moving Windows Between Screens\n\n**Using Screen Index (0-based):**\n```bash\n# Move window to specific screen by index\npeekaboo window resize --app Safari --target-screen 0 # Primary screen\npeekaboo window resize --app Terminal --target-screen 1 # Second screen\npeekaboo window resize --app Notes --target-screen 2 # Third screen\n```\n\n**Using Screen Presets:**\n```bash\n# Move to next/previous screen\npeekaboo window resize --app Safari --screen-preset next\npeekaboo window resize --app Terminal --screen-preset previous\n\n# Move to primary screen (with menu bar)\npeekaboo window resize --app Notes --screen-preset primary\n\n# Keep on same screen (useful with other resize options)\npeekaboo window resize --app TextEdit --screen-preset same --preset left_half\n```\n\n#### Combined Screen and Window Operations\n\nYou can combine screen movement with window positioning:\n```bash\n# Move to screen 1 and maximize\npeekaboo window resize --app Safari --target-screen 1 --preset maximize\n\n# Move to next screen and position on left half\npeekaboo window resize --app Terminal --screen-preset next --preset left_half\n\n# Move to screen 0 at specific coordinates\npeekaboo window resize --app Notes --target-screen 0 --x 100 --y 100\n\n# Move to primary screen with custom size\npeekaboo window resize --app TextEdit --screen-preset primary --width 1200 --height 800\n```\n\n#### How It Works\n\n- **Unified Coordinate System**: macOS uses a single coordinate space across all screens\n- **Smart Positioning**: When moving windows between screens without explicit coordinates, windows maintain their relative position (e.g., a window at 25% from the left edge stays at 25% on the new screen)\n- **Screen Detection**: Windows are assigned to screens based on their center point\n- **0-Based Indexing**: Screens are indexed starting from 0, matching macOS's internal ordering\n\n#### Multi-Screen with AI Agent\n\nThe AI agent understands multi-screen commands:\n```bash\npeekaboo agent \"Move all Safari windows to the external display\"\npeekaboo agent \"Put Terminal on my second screen\"\npeekaboo agent \"Arrange windows with Safari on the left screen and Notes on the right\"\n```\n\n### 📋 The `menu` Tool\n\nInteract with application menu bars and system menu extras:\n\n```typescript\n// List all menus and items for an app\nawait menu({ action: \"list\", app: \"Calculator\" })\n\n// Click a simple menu item\nawait menu({ action: \"click\", app: \"Safari\", item: \"New Window\" })\n\n// Navigate nested menus with path\nawait menu({ action: \"click\", app: \"TextEdit\", path: \"Format > Font > Bold\" })\n\n// Click system menu extras (WiFi, Bluetooth, etc.)\nawait menu({ action: \"click-extra\", title: \"WiFi\" })\n```\n\n#### Menu Subcommands\n- **list** - List all menus and their items (including keyboard shortcuts)\n- **list-all** - List menus for the frontmost application\n- **click** - Click a menu item (default if not specified)\n- **click-extra** - Click system menu extras in the status bar\n\n#### Key Features\n- **Pure Accessibility** - Extracts menu structure without clicking or opening menus\n- **Full Hierarchy** - Discovers all submenus and nested items\n- **Keyboard Shortcuts** - Shows all available keyboard shortcuts\n- **Smart Discovery** - AI agents can use list to discover available options\n\n### 🚀 The `app` Tool\n\nControl applications - launch, quit, focus, hide, and switch between apps:\n\n```typescript\n// Launch an application\nawait app({ action: \"launch\", name: \"Safari\" })\n\n// Quit an application\nawait app({ action: \"quit\", name: \"TextEdit\" })\n\n// Force quit\nawait app({ action: \"quit\", name: \"Notes\", force: true })\n\n// Focus/switch to app\nawait app({ action: \"focus\", name: \"Google Chrome\" })\n\n// Hide/unhide apps\nawait app({ action: \"hide\", name: \"Finder\" })\nawait app({ action: \"unhide\", name: \"Finder\" })\n```\n\n### 🎯 The `dock` Tool\n\nInteract with the macOS Dock:\n\n```typescript\n// List all dock items\nawait dock({ action: \"list\" })\n\n// Launch app from dock\nawait dock({ action: \"launch\", app: \"Safari\" })\n\n// Right-click on dock item\nawait dock({ action: \"right-click\", app: \"Finder\" })\n\n// Show/hide dock\nawait dock({ action: \"hide\" })\nawait dock({ action: \"show\" })\n```\n\n### 💬 The `dialog` Tool\n\nHandle system dialogs and alerts:\n\n```typescript\n// List open dialogs\nawait dialog({ action: \"list\" })\n\n// Click dialog button\nawait dialog({ action: \"click\", button: \"OK\" })\n\n// Input text in dialog field\nawait dialog({ action: \"input\", text: \"filename.txt\" })\n\n// Select file in open/save dialog\nawait dialog({ action: \"file\", path: \"/Users/me/Documents/file.pdf\" })\n\n// Dismiss dialog\nawait dialog({ action: \"dismiss\" })\n```\n\n### 🧹 The `clean` Tool\n\nClean up session cache and temporary files:\n\n```typescript\n// Clean all sessions\nawait clean({})\n\n// Clean sessions older than 7 hours\nawait clean({ older_than: 7 })\n\n// Clean specific session\nawait clean({ session: \"session_123\" })\n\n// Dry run to see what would be cleaned\nawait clean({ dry_run: true })\n```\n\n### Session Management\n\nPeekaboo v3 uses sessions to maintain UI state across commands:\n\n- Sessions are created automatically by the `see` tool\n- Each session stores screenshot data and element mappings\n- Sessions persist in `~/.peekaboo/session//`\n- Element IDs remain consistent within a session\n- Sessions are automatically cleaned up on process exit\n\n### Best Practices\n\n1. **Always start with `see`** - Capture the current UI state before interacting\n2. **Use element IDs when possible** - More reliable than coordinate clicking\n3. **Add delays for animations** - Use `sleep` after actions that trigger animations\n4. **Verify actions** - Call `see` again to confirm actions succeeded\n5. **Handle errors gracefully** - Check if elements exist before interacting\n6. **Clean up sessions** - Use the `clean` tool periodically\n\n### Example Workflows\n\n#### Login Automation\n```typescript\n// 1. See the login form\nconst { elements } = await see({ app_target: \"MyApp\" })\n\n// 2. Fill in credentials\nawait click({ on: \"T1\" }) // Click email field\nawait type({ text: \"user@example.com\" })\n\nawait click({ on: \"T2\" }) // Click password field \nawait type({ text: \"password123\" })\n\n// 3. Submit\nawait click({ query: \"Sign In\" })\n\n// 4. Wait and verify\nawait sleep({ duration: 2000 })\nawait see({ app_target: \"MyApp\" }) // Verify logged in\n```\n\n#### Web Search\n```typescript\n// 1. Focus browser\nawait see({ app_target: \"Safari\" })\n\n// 2. Open new tab\nawait hotkey({ keys: \"cmd,t\" })\n\n// 3. Type search\nawait type({ text: \"Peekaboo MCP automation\" })\nawait type({ text: \"{return}\" })\n\n// 4. Wait for results\nawait sleep({ duration: 3000 })\n\n// 5. Click first result\nawait see({ app_target: \"Safari\" })\nawait click({ on: \"L1\" })\n```\n\n#### Form Filling\n```typescript\n// 1. Capture form\nconst { elements } = await see({ app_target: \"Forms\" })\n\n// 2. Fill each field\nfor (const field of elements.text_fields) {\n await click({ on: field.id })\n await type({ text: \"Test data\", clear: true })\n}\n\n// 3. Check all checkboxes\nfor (const checkbox of elements.checkboxes) {\n if (!checkbox.checked) {\n await click({ on: checkbox.id })\n }\n}\n\n// 4. Submit\nawait click({ query: \"Submit\" })\n```\n\n### Troubleshooting\n\n1. **Elements not found** - Ensure the UI is visible and not obscured\n2. **Clicks not working** - Try increasing `wait_for` timeout\n3. **Wrong element clicked** - Use specific element IDs instead of queries\n4. **Session errors** - Run `clean` tool to clear corrupted sessions\n5. **Permissions denied** - Grant Accessibility permission in System Settings\n\n### Debugging with Logs\n\nPeekaboo uses macOS's unified logging system. Use `pblog` to monitor logs:\n\n```bash\n# View recent logs\n./scripts/pblog.sh\n\n# Stream logs continuously\n./scripts/pblog.sh -f\n\n# Debug specific issues\n./scripts/pblog.sh -c ClickService -d\n```\n\n**Note**: macOS redacts log values by default, showing ``. \nSee [docs/pblog-guide.md](docs/pblog-guide.md) and [docs/logging-profiles/README.md](docs/logging-profiles/README.md) for solutions.\n\n## 🔧 Configuration\n\nFor full configuration + environment variable tables, see [docs/configuration.md](docs/configuration.md).\n\n## 🎨 Setting Up Local AI with Ollama\n\nNeed fully local models or Ultrathink experimentation? Follow the dedicated playbook in [docs/ollama.md](docs/ollama.md) for installation, recommended models, environment variables, and troubleshooting tips. At runtime you can point Peekaboo at your Ollama server with `PEEKABOO_AI_PROVIDERS=\"ollama/llama3.3\" peekaboo agent \"…\"`.\n\n## 📋 Requirements\n\nPeekaboo needs macOS 14.0+, Screen Recording permission, and (ideally) Accessibility access. Follow [docs/permissions.md](docs/permissions.md) for step-by-step instructions plus performance tips.\n\n## 🏗️ Building from Source\n\nSee [docs/building.md](docs/building.md) for prerequisites, pnpm build commands, and release script pointers.\n\n## 👻 Poltergeist\n\nUse the watcher by following [docs/poltergeist.md](docs/poltergeist.md); it covers start/stop commands, tuning, and queue behavior.\n\n## 🧪 Testing\n\n### Running Tests\n\nPeekaboo uses Swift Testing framework (Swift 6.0+) for all test suites:\n\n```bash\n# Run all tests\nswift test\n\n# Run specific test target\nswift test --filter PeekabooTests\n\n# Run tests with verbose output\nswift test --verbose\n```\n\n### Testing the CLI\n\n```bash\n# Test CLI directly\npeekaboo list server_status\npeekaboo image --mode screen --path test.png\npeekaboo image --analyze \"What is shown?\" --path test.png\n\n# Test MCP server\nnpx @modelcontextprotocol/inspector npx -y @steipete/peekaboo-mcp\n```\n\n## 📚 Documentation\n\n- [API Documentation](./docs/spec.md)\n- [Contributing Guide](https://github.com/steipete/Peekaboo?tab=readme-ov-file#-contributing)\n- [Blog Post](https://steipete.me/posts/2025/peekaboo-2-freeing-the-cli-from-its-mcp-shackles/)\n\n## 🐛 Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| `Permission denied` | Grant Screen Recording permission in System Settings |\n| `Window not found` | Try using fuzzy matching or list windows first |\n| `AI analysis failed` | Check API keys and provider configuration |\n| `Command not found` | Ensure Peekaboo is in your PATH or use full path |\n\nEnable debug logging for more details:\n```bash\nexport PEEKABOO_LOG_LEVEL=debug\npeekaboo list server_status\n```\n\nFor step-by-step debugging, use the verbose flag:\n```bash\npeekaboo image --app Safari --verbose 2>&1 | less\n```\n\n## 🛠️ Development\n\n### Poltergeist - Automatic CLI Builder\n\nPeekaboo includes **Poltergeist**, an automatic build system that watches Swift source files and rebuilds the CLI in the background. This ensures your CLI binary is always up-to-date during development.\n\n```bash\n# Start Poltergeist (runs in background)\nnpm run poltergeist:haunt\n\n# Check status\nnpm run poltergeist:status\n\n# Stop Poltergeist\nnpm run poltergeist:rest\n```\n\n**Key features:**\n- Watches all Swift source files automatically\n- Smart wrapper script (`./scripts/peekaboo-wait.sh`) handles build coordination\n- Exit code 42 indicates build failure - fix immediately\n- See [Poltergeist repository](https://github.com/steipete/poltergeist) for full documentation\n\n### Building from Source\n\n```bash\n# Build everything\nnpm run build:all\n\n# Build CLI only\nnpm run build:swift\n\n# Build TypeScript server\nnpm run build\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to the branch\n5. Open a Pull Request\n\n## 📝 License\n\nMIT License - see [LICENSE](./LICENSE) file for details.\n\n## 👤 Author\n\nCreated by [Peter Steinberger](https://steipete.com) - [@steipete](https://github.com/steipete)\n\n## 🙏 Acknowledgments\n\n- Apple's ScreenCaptureKit for blazing-fast captures\n- The MCP team for the Model Context Protocol\n- The Swift and TypeScript communities\n\n## 📊 Coverage\n\n| Date | Command | Scope | Line Coverage |\n| ---------- | ------------------------------------------------------------------ | -------------------------------------- | ------------- |\n| 2025-11-13 | ``cd Apps/CLI && swift test -Xswiftc -DPEEKABOO_SKIP_AUTOMATION --enable-code-coverage && xcrun llvm-profdata merge -sparse .build/arm64-apple-macosx/debug/codecov/*.profraw -o .build/arm64-apple-macosx/debug/codecov/default.profdata && xcrun llvm-cov report .build/arm64-apple-macosx/debug/peekabooPackageTests.xctest/Contents/MacOS/peekabooPackageTests -instr-profile .build/arm64-apple-macosx/debug/codecov/default.profdata`` | CLI + Core services under `PEEKABOO_SKIP_AUTOMATION` (non-interactive subset) | 9.82 % |\n| 2025-11-12 | `./runner swift test --package-path Apps/CLI --enable-code-coverage` | Entire workspace (Peekaboo + subrepos) | 8.38 % |\n\n> Coverage generated via `xcrun llvm-cov report Apps/CLI/.build/arm64-apple-macosx/debug/peekabooPackageTests.xctest/Contents/MacOS/peekabooPackageTests -instr-profile Apps/CLI/.build/arm64-apple-macosx/debug/codecov/default.profdata`. Because the CLI target depends on AXorcist, Commander, Tachikoma, and TauTUI, the figure reflects the aggregate workspace, even though automation-heavy suites remain disabled during headless runs.\n","name","English","tag","en-US",{"_44":45,"_13":46,"_55":34,"_56":34,"_35":36,"_16":57,"_58":59,"_85":86,"_93":-5,"_94":95,"_96":-5,"_97":98,"_180":181,"_186":-5,"_66":159,"_187":188,"_69":189,"_190":191},"addedAt","2025-05-27T23:03:08.657175Z",[47,48,49,50,51,52,53,54],"category:image-and-video-processing","category:autonomous-agents","environment:local","hosting:local-only","language:swift","security_grade:a","quality_grade:a","license_grade:a","descriptionMarkdown","descriptionPlainText",7101,"integrations",[60,71,78],{"_61":62,"_33":68,"_69":70},"brand",{"_63":64,"_39":65,"_66":67},"logoSvgPath","M0 14.727h.941v-2.453c0-.484.318-.835.771-.835.439 0 .71.276.71.722v2.566h.915V12.25c0-.48.31-.812.764-.812.46 0 .718.28.718.77v2.518h.94v-2.748c0-.801-.517-1.334-1.307-1.334-.578 0-1.054.31-1.247.805h-.023c-.147-.514-.552-.805-1.118-.805-.545 0-.968.306-1.142.771H.903v-.695H0v4.006zm7.82-.646c-.408 0-.68-.208-.68-.537 0-.318.26-.522.714-.552l.926-.057v.307c0 .483-.427.839-.96.839zm-.284.71c.514 0 1.017-.268 1.248-.703h.018v.639h.908v-2.76c0-.804-.647-1.33-1.64-1.33-1.021 0-1.66.537-1.701 1.285h.873c.06-.332.344-.548.79-.548.464 0 .748.242.748.662v.287l-1.058.06c-.976.061-1.524.488-1.524 1.199 0 .721.564 1.209 1.338 1.209zm6.305-2.642c-.065-.843-.719-1.512-1.777-1.512-1.164 0-1.92.805-1.92 2.087 0 1.3.756 2.082 1.928 2.082 1.005 0 1.697-.59 1.772-1.485h-.888c-.087.453-.397.725-.873.725-.597 0-.982-.483-.982-1.322 0-.824.381-1.323.975-1.323.502 0 .8.321.876.748h.889zm2.906-2.967c-1.591 0-2.589 1.085-2.589 2.82 0 1.735.998 2.816 2.59 2.816 1.586 0 2.584-1.081 2.584-2.816 0-1.735-.997-2.82-2.585-2.82zm0 .832c.971 0 1.591.77 1.591 1.988 0 1.213-.62 1.984-1.59 1.984-.976 0-1.592-.77-1.592-1.984 0-1.217.616-1.988 1.591-1.988zm2.982 3.178c.042 1.006.866 1.626 2.12 1.626 1.32 0 2.151-.65 2.151-1.686 0-.813-.469-1.27-1.576-1.523l-.627-.144c-.67-.158-.945-.37-.945-.733 0-.453.415-.756 1.032-.756.623 0 1.05.306 1.096.817h.93c-.023-.96-.817-1.61-2.019-1.61-1.187 0-2.03.653-2.03 1.62 0 .78.477 1.263 1.482 1.494l.707.166c.688.163.967.39.967.782 0 .454-.457.779-1.115.779-.665 0-1.167-.329-1.228-.832h-.945z","macOS","slug","macos","Enables comprehensive screen capture capabilities on macOS, including capturing entire screens, specific application windows, or all windows of an app with various formatting options.","uid","i5ugsrhghk",{"_61":72,"_33":76,"_69":77},{"_63":73,"_39":74,"_66":75},"M16.361 10.26a.894.894 0 0 0-.558.47l-.072.148.001.207c0 .193.004.217.059.353.076.193.152.312.291.448.24.238.51.3.872.205a.86.86 0 0 0 .517-.436.752.752 0 0 0 .08-.498c-.064-.453-.33-.782-.724-.897a1.06 1.06 0 0 0-.466 0zm-9.203.005c-.305.096-.533.32-.65.639a1.187 1.187 0 0 0-.06.52c.057.309.31.59.598.667.362.095.632.033.872-.205.14-.136.215-.255.291-.448.055-.136.059-.16.059-.353l.001-.207-.072-.148a.894.894 0 0 0-.565-.472 1.02 1.02 0 0 0-.474.007Zm4.184 2c-.131.071-.223.25-.195.383.031.143.157.288.353.407.105.063.112.072.117.136.004.038-.01.146-.029.243-.02.094-.036.194-.036.222.002.074.07.195.143.253.064.052.076.054.255.059.164.005.198.001.264-.03.169-.082.212-.234.15-.525-.052-.243-.042-.28.087-.355.137-.08.281-.219.324-.314a.365.365 0 0 0-.175-.48.394.394 0 0 0-.181-.033c-.126 0-.207.03-.355.124l-.085.053-.053-.032c-.219-.13-.259-.145-.391-.143a.396.396 0 0 0-.193.032zm.39-2.195c-.373.036-.475.05-.654.086-.291.06-.68.195-.951.328-.94.46-1.589 1.226-1.787 2.114-.04.176-.045.234-.045.53 0 .294.005.357.043.524.264 1.16 1.332 2.017 2.714 2.173.3.033 1.596.033 1.896 0 1.11-.125 2.064-.727 2.493-1.571.114-.226.169-.372.22-.602.039-.167.044-.23.044-.523 0-.297-.005-.355-.045-.531-.288-1.29-1.539-2.304-3.072-2.497a6.873 6.873 0 0 0-.855-.031zm.645.937a3.283 3.283 0 0 1 1.44.514c.223.148.537.458.671.662.166.251.26.508.303.82.02.143.01.251-.043.482-.08.345-.332.705-.672.957a3.115 3.115 0 0 1-.689.348c-.382.122-.632.144-1.525.138-.582-.006-.686-.01-.853-.042-.57-.107-1.022-.334-1.35-.68-.264-.28-.385-.535-.45-.946-.03-.192.025-.509.137-.776.136-.326.488-.73.836-.963.403-.269.934-.46 1.422-.512.187-.02.586-.02.773-.002zm-5.503-11a1.653 1.653 0 0 0-.683.298C5.617.74 5.173 1.666 4.985 2.819c-.07.436-.119 1.04-.119 1.503 0 .544.064 1.24.155 1.721.02.107.031.202.023.208a8.12 8.12 0 0 1-.187.152 5.324 5.324 0 0 0-.949 1.02 5.49 5.49 0 0 0-.94 2.339 6.625 6.625 0 0 0-.023 1.357c.091.78.325 1.438.727 2.04l.13.195-.037.064c-.269.452-.498 1.105-.605 1.732-.084.496-.095.629-.095 1.294 0 .67.009.803.088 1.266.095.555.288 1.143.503 1.534.071.128.243.393.264.407.007.003-.014.067-.046.141a7.405 7.405 0 0 0-.548 1.873c-.062.417-.071.552-.071.991 0 .56.031.832.148 1.279L3.42 24h1.478l-.05-.091c-.297-.552-.325-1.575-.068-2.597.117-.472.25-.819.498-1.296l.148-.29v-.177c0-.165-.003-.184-.057-.293a.915.915 0 0 0-.194-.25 1.74 1.74 0 0 1-.385-.543c-.424-.92-.506-2.286-.208-3.451.124-.486.329-.918.544-1.154a.787.787 0 0 0 .223-.531c0-.195-.07-.355-.224-.522a3.136 3.136 0 0 1-.817-1.729c-.14-.96.114-2.005.69-2.834.563-.814 1.353-1.336 2.237-1.475.199-.033.57-.028.776.01.226.04.367.028.512-.041.179-.085.268-.19.374-.431.093-.215.165-.333.36-.576.234-.29.46-.489.822-.729.413-.27.884-.467 1.352-.561.17-.035.25-.04.569-.04.319 0 .398.005.569.04a4.07 4.07 0 0 1 1.914.997c.117.109.398.457.488.602.034.057.095.177.132.267.105.241.195.346.374.43.14.068.286.082.503.045.343-.058.607-.053.943.016 1.144.23 2.14 1.173 2.581 2.437.385 1.108.276 2.267-.296 3.153-.097.15-.193.27-.333.419-.301.322-.301.722-.001 1.053.493.539.801 1.866.708 3.036-.062.772-.26 1.463-.533 1.854a2.096 2.096 0 0 1-.224.258.916.916 0 0 0-.194.25c-.054.109-.057.128-.057.293v.178l.148.29c.248.476.38.823.498 1.295.253 1.008.231 2.01-.059 2.581a.845.845 0 0 0-.044.098c0 .006.329.009.732.009h.73l.02-.074.036-.134c.019-.076.057-.3.088-.516.029-.217.029-1.016 0-1.258-.11-.875-.295-1.57-.597-2.226-.032-.074-.053-.138-.046-.141.008-.005.057-.074.108-.152.376-.569.607-1.284.724-2.228.031-.26.031-1.378 0-1.628-.083-.645-.182-1.082-.348-1.525a6.083 6.083 0 0 0-.329-.7l-.038-.064.131-.194c.402-.604.636-1.262.727-2.04a6.625 6.625 0 0 0-.024-1.358 5.512 5.512 0 0 0-.939-2.339 5.325 5.325 0 0 0-.95-1.02 8.097 8.097 0 0 1-.186-.152.692.692 0 0 1 .023-.208c.208-1.087.201-2.443-.017-3.503-.19-.924-.535-1.658-.98-2.082-.354-.338-.716-.482-1.15-.455-.996.059-1.8 1.205-2.116 3.01a6.805 6.805 0 0 0-.097.726c0 .036-.007.066-.015.066a.96.96 0 0 1-.149-.078A4.857 4.857 0 0 0 12 3.03c-.832 0-1.687.243-2.456.698a.958.958 0 0 1-.148.078c-.008 0-.015-.03-.015-.066a6.71 6.71 0 0 0-.097-.725C8.997 1.392 8.337.319 7.46.048a2.096 2.096 0 0 0-.585-.041Zm.293 1.402c.248.197.523.759.682 1.388.03.113.06.244.069.292.007.047.026.152.041.233.067.365.098.76.102 1.24l.002.475-.12.175-.118.178h-.278c-.324 0-.646.041-.954.124l-.238.06c-.033.007-.038-.003-.057-.144a8.438 8.438 0 0 1 .016-2.323c.124-.788.413-1.501.696-1.711.067-.05.079-.049.157.013zm9.825-.012c.17.126.358.46.498.888.28.854.36 2.028.212 3.145-.019.14-.024.151-.057.144l-.238-.06a3.693 3.693 0 0 0-.954-.124h-.278l-.119-.178-.119-.175.002-.474c.004-.669.066-1.19.214-1.772.157-.623.434-1.185.68-1.382.078-.062.09-.063.159-.012z","Ollama","ollama","Enables local AI image analysis of screenshots through Ollama, supporting models like LLaVA and Qwen2-VL for vision tasks without sending data to the cloud.","9hmx0u6qrb",{"_61":79,"_33":83,"_69":84},{"_63":80,"_39":81,"_66":82},"M22.2819 9.8211a5.9847 5.9847 0 0 0-.5157-4.9108 6.0462 6.0462 0 0 0-6.5098-2.9A6.0651 6.0651 0 0 0 4.9807 4.1818a5.9847 5.9847 0 0 0-3.9977 2.9 6.0462 6.0462 0 0 0 .7427 7.0966 5.98 5.98 0 0 0 .511 4.9107 6.051 6.051 0 0 0 6.5146 2.9001A5.9847 5.9847 0 0 0 13.2599 24a6.0557 6.0557 0 0 0 5.7718-4.2058 5.9894 5.9894 0 0 0 3.9977-2.9001 6.0557 6.0557 0 0 0-.7475-7.0729zm-9.022 12.6081a4.4755 4.4755 0 0 1-2.8764-1.0408l.1419-.0804 4.7783-2.7582a.7948.7948 0 0 0 .3927-.6813v-6.7369l2.02 1.1686a.071.071 0 0 1 .038.052v5.5826a4.504 4.504 0 0 1-4.4945 4.4944zm-9.6607-4.1254a4.4708 4.4708 0 0 1-.5346-3.0137l.142.0852 4.783 2.7582a.7712.7712 0 0 0 .7806 0l5.8428-3.3685v2.3324a.0804.0804 0 0 1-.0332.0615L9.74 19.9502a4.4992 4.4992 0 0 1-6.1408-1.6464zM2.3408 7.8956a4.485 4.485 0 0 1 2.3655-1.9728V11.6a.7664.7664 0 0 0 .3879.6765l5.8144 3.3543-2.0201 1.1685a.0757.0757 0 0 1-.071 0l-4.8303-2.7865A4.504 4.504 0 0 1 2.3408 7.872zm16.5963 3.8558L13.1038 8.364 15.1192 7.2a.0757.0757 0 0 1 .071 0l4.8303 2.7913a4.4944 4.4944 0 0 1-.6765 8.1042v-5.6772a.79.79 0 0 0-.407-.667zm2.0107-3.0231l-.142-.0852-4.7735-2.7818a.7759.7759 0 0 0-.7854 0L9.409 9.2297V6.8974a.0662.0662 0 0 1 .0284-.0615l4.8303-2.7866a4.4992 4.4992 0 0 1 6.6802 4.66zM8.3065 12.863l-2.02-1.1638a.0804.0804 0 0 1-.038-.0567V6.0742a4.4992 4.4992 0 0 1 7.3757-3.4537l-.142.0805L8.704 5.459a.7948.7948 0 0 0-.3927.6813zm1.0976-2.3654l2.602-1.4998 2.6069 1.4998v2.9994l-2.5974 1.4997-2.6067-1.4997Z","OpenAI","openai","Provides integration with OpenAI's vision models (like GPT-4o) for analyzing captured screenshots through the OpenAI API.","92m75skkw1","namespace",{"_87":88,"_66":92},"owner",{"_89":90},"githubAccount",{"_91":92},"login","steipete","readmeMarkdown","recentUsage",0,"redditPostExternalId","repository",{"_99":100,"_144":145,"_148":149,"_169":-5,"_170":171,"_172":173,"_177":178},"argumentsJsonSchema",{"_101":102,"_141":142,"_106":143},"properties",{"_103":104,"_108":109,"_113":114,"_117":118,"_121":122,"_125":126,"_129":130,"_133":134,"_137":138},"OPENAI_API_KEY",{"_33":105,"_106":107},"Your OpenAI API key for using OpenAI models for image analysis.","type","string","PEEKABOO_CLI_PATH",{"_110":111,"_33":112,"_106":107},"default","uses bundled CLI","Optional override for the Swift peekaboo CLI executable path.","PEEKABOO_LOG_FILE",{"_110":115,"_33":116,"_106":107},"~/Library/Logs/peekaboo-mcp.log","Path to the server's log file. If the specified directory is not writable, falls back to the system temp directory.","PEEKABOO_LOG_LEVEL",{"_110":119,"_33":120,"_106":107},"info","Logging level (trace, debug, info, warn, error, fatal).","PEEKABOO_CLI_TIMEOUT",{"_110":123,"_33":124,"_106":107},"30000","Timeout in milliseconds for Swift CLI operations. Prevents hanging processes.","PEEKABOO_AI_PROVIDERS",{"_110":127,"_33":128,"_106":107},"","JSON string defining AI providers for image analysis. Format: 'provider_name/model_identifier' using commas or semicolons as separators.","PEEKABOO_CONSOLE_LOGGING",{"_110":131,"_33":132,"_106":107},"false","Boolean (\"true\"/\"false\") for development console logs.","PEEKABOO_OLLAMA_BASE_URL",{"_110":135,"_33":136,"_106":107},"http://localhost:11434","Base URL for the Ollama API server. Only needed if Ollama is running on a non-default address.","PEEKABOO_DEFAULT_SAVE_PATH",{"_110":139,"_33":140,"_106":107},"System temp directory","Default directory for saving captured images when no path is specified.","required",[],"object","githubProject",{"_37":38,"_146":147},"url","https://github.com/steipete/peekaboo","githubRepository",{"_150":151,"_152":153,"_154":155,"_16":156,"_157":158,"_39":159,"_87":160,"_162":163,"_164":165,"_167":168},"defaultBranch","main","fullName","steipete/Peekaboo","githubTreeId",3438775,14515,"language","Swift","Peekaboo",{"_91":92,"_69":161},"1TS5dAfshL","recentStargazers",16,"spdxLicense",{"_39":166},"MIT License","stargazers",783,"glamaJson","inspectable",true,"npmPackage",{"_39":174,"_175":176},"peekaboo","weeklyDownloads",7465,"supportedPlatforms",[179],"MACOS","scores",{"_182":183,"_184":183,"_185":183},"license",100,"quality","security","simpleIcon","toolCount",3,"u4wzs4fggx","updatedAt","2025-11-19T01:15:53.475240Z","meta",[194,197,199,206,209,211,214,217,220,223,226,228,231,234,236,238,240,242,244],{"_195":196},"title","Peekaboo MCP | Glama",{"_198":34,"_39":33},"content",{"_200":201,"_202":203,"_204":205},"href","https://glama.ai/mcp/servers/@steipete/Peekaboo","rel","canonical","tagName","link",{"_198":36,"_207":208},"property","og:title",{"_198":34,"_207":210},"og:description",{"_198":212,"_207":213},"https://glama.ai/logo.png","og:logo",{"_198":215,"_207":216},"https://glama.ai/mcp/servers/@steipete/Peekaboo/og-image","og:image",{"_198":218,"_207":219},"630","og:image:height",{"_198":221,"_207":222},"1200","og:image:width",{"_198":224,"_207":225},"website","og:type",{"_198":201,"_207":227},"og:url",{"_198":229,"_207":230},"Glama – MCP Hosting Platform","og:site_name",{"_198":232,"_39":233},"summary_large_image","twitter:card",{"_198":229,"_39":235},"twitter:title",{"_198":34,"_39":237},"twitter:description",{"_198":215,"_39":239},"twitter:image",{"_198":218,"_39":241},"twitter:image:height",{"_198":221,"_39":243},"twitter:image:width",{"_245":246},"script:ld+json",{"_247":248,"_249":250},"@context","http://schema.org","@graph",[251],{"_247":252,"_253":254,"_255":256},"https://schema.org","@type","BreadcrumbList","itemListElement",[257,264,267,270],{"_253":258,"_259":260,"_39":261,"_262":263},"ListItem","item","https://glama.ai/","Glama","position",1,{"_253":258,"_259":265,"_39":266,"_262":22},"https://glama.ai/mcp","MCP",{"_253":258,"_259":268,"_39":269,"_262":188},"https://glama.ai/mcp/servers","Servers",{"_253":258,"_259":201,"_39":36,"_262":271},4,"visitorIsMaintainer",false,"routes/_public/mcp/servers/~namespace/~slug/_pages/_explorer/blob/~commit/~/_route",{"_276":277,"_31":283,"_315":316,"_192":328,"_326":127,"_352":353},"blob",{"_198":278,"_279":280,"_281":282},"packages:\n - '.'\noverrides:\n '@steipete/oracle': link:../oracle\n oracle: link:../oracle\n","fileName","pnpm-workspace.yaml","size",91,{"_44":45,"_13":284,"_55":34,"_56":34,"_35":36,"_16":57,"_58":285,"_85":292,"_93":-5,"_94":95,"_96":-5,"_97":295,"_180":314,"_186":-5,"_66":159,"_187":188,"_69":189,"_190":191},[47,48,49,50,51,52,53,54],[286,288,290],{"_61":287,"_33":68,"_69":70},{"_63":64,"_39":65,"_66":67},{"_61":289,"_33":76,"_69":77},{"_63":73,"_39":74,"_66":75},{"_61":291,"_33":83,"_69":84},{"_63":80,"_39":81,"_66":82},{"_87":293,"_66":92},{"_89":294},{"_91":92},{"_99":296,"_144":308,"_148":309,"_169":-5,"_170":171,"_172":312,"_177":313},{"_101":297,"_141":307,"_106":143},{"_103":298,"_108":299,"_113":300,"_117":301,"_121":302,"_125":303,"_129":304,"_133":305,"_137":306},{"_33":105,"_106":107},{"_110":111,"_33":112,"_106":107},{"_110":115,"_33":116,"_106":107},{"_110":119,"_33":120,"_106":107},{"_110":123,"_33":124,"_106":107},{"_110":127,"_33":128,"_106":107},{"_110":131,"_33":132,"_106":107},{"_110":135,"_33":136,"_106":107},{"_110":139,"_33":140,"_106":107},[],{"_37":38,"_146":147},{"_150":151,"_152":153,"_154":155,"_16":156,"_157":158,"_39":159,"_87":310,"_162":163,"_164":311,"_167":168},{"_91":92,"_69":161},{"_39":166},{"_39":174,"_175":176},[179],{"_182":183,"_184":183,"_185":183},"member",{"_317":318,"_321":322,"_323":280,"_154":324,"_325":-5,"_326":280,"_327":171,"_281":282,"_106":276},"commit",{"_319":320},"sha","5c5030f3bbcdbd20f293a25811f62ef2a2c44711","contentStoredObjectPointerId",19427138,"fullPath",3374778,"indexable","path","safeToDisplayAsText",[329,331,333,335,337,338,339,341,342,343,344,345,346,347,348,349,350,351],{"_195":330},"pnpm-workspace.yaml | Peekaboo MCP | Glama",{"_198":332,"_39":33},"Enterprise-grade security, privacy, and features like agents, MCP, prompt templates, and more.",{"_200":334,"_202":203,"_204":205},"https://glama.ai/mcp/servers/@steipete/Peekaboo/blob/5c5030f3bbcdbd20f293a25811f62ef2a2c44711/",{"_198":336,"_207":208},"pnpm-workspace.yaml | Peekaboo MCP",{"_198":332,"_207":210},{"_198":212,"_207":213},{"_198":340,"_207":216},"https://glama.ai/generated-images/og?title=pnpm-workspace.yaml+%7C+Peekaboo+MCP",{"_198":218,"_207":219},{"_198":221,"_207":222},{"_198":224,"_207":225},{"_198":334,"_207":227},{"_198":229,"_207":230},{"_198":232,"_39":233},{"_198":229,"_39":235},{"_198":332,"_39":237},{"_198":340,"_39":239},{"_198":218,"_39":241},{"_198":221,"_39":243},"treeMembers",[354,358,361,364,367,370,373,376,379,382,385,388,391,394,397,400,403,406,409,412,415,418,421,423,426,429,432,435,438,441,444,447,450],{"_317":355,"_323":356,"_326":356,"_106":357},{"_319":320},"Apps","tree",{"_317":359,"_323":360,"_326":360,"_106":357},{"_319":320},"assets",{"_317":362,"_323":363,"_326":363,"_106":357},{"_319":320},".claude",{"_317":365,"_323":366,"_326":366,"_106":357},{"_319":320},"Core",{"_317":368,"_323":369,"_326":369,"_106":357},{"_319":320},".cursor",{"_317":371,"_323":372,"_326":372,"_106":357},{"_319":320},"docs",{"_317":374,"_323":375,"_326":375,"_106":357},{"_319":320},"Examples",{"_317":377,"_323":378,"_326":378,"_106":357},{"_319":320},"experiments",{"_317":380,"_323":381,"_326":381,"_106":357},{"_319":320},".github",{"_317":383,"_323":384,"_326":384,"_106":357},{"_319":320},"Helpers",{"_317":386,"_323":387,"_326":387,"_106":357},{"_319":320},"homebrew",{"_317":389,"_323":390,"_326":390,"_106":357},{"_319":320},"scripts",{"_317":392,"_323":393,"_326":393,"_106":276},{"_319":320},"AGENTS.md",{"_317":395,"_323":396,"_326":396,"_106":276},{"_319":320},"CHANGELOG.md",{"_317":398,"_323":399,"_326":399,"_106":276},{"_319":320},"CLAUDE.md",{"_317":401,"_323":402,"_326":402,"_106":276},{"_319":320},".envrc",{"_317":404,"_323":405,"_326":405,"_106":276},{"_319":320},".gitignore",{"_317":407,"_323":408,"_326":408,"_106":276},{"_319":320},".gitmodules",{"_317":410,"_323":411,"_326":411,"_106":276},{"_319":320},"LICENSE",{"_317":413,"_323":414,"_326":414,"_106":276},{"_319":320},".npmignore",{"_317":416,"_323":417,"_326":417,"_106":276},{"_319":320},"package.json",{"_317":419,"_323":420,"_326":420,"_106":276},{"_319":320},"pnpm-lock.yaml",{"_317":422,"_323":280,"_326":280,"_106":276},{"_319":320},{"_317":424,"_323":425,"_326":425,"_106":276},{"_319":320},"poltergeist.config.json",{"_317":427,"_323":428,"_326":428,"_106":276},{"_319":320},"README.md",{"_317":430,"_323":431,"_326":431,"_106":276},{"_319":320},"runner",{"_317":433,"_323":434,"_326":434,"_106":276},{"_319":320},".swiftformat",{"_317":436,"_323":437,"_326":437,"_106":276},{"_319":320},".swiftlint-ci.yml",{"_317":439,"_323":440,"_326":440,"_106":276},{"_319":320},".swiftlint.yml",{"_317":442,"_323":443,"_326":443,"_106":276},{"_319":320},"test-direct-grok.swift",{"_317":445,"_323":446,"_326":446,"_106":276},{"_319":320},"test-formatter-output.py",{"_317":448,"_323":449,"_326":449,"_106":276},{"_319":320},"version.json",{"_317":451,"_323":452,"_326":452,"_106":276},{"_319":320},".watchmanconfig","actionData","errors"]

MCP directory API