peekaboo

Peekaboo is a comprehensive macOS CLI utility designed for advanced UI automation and desktop environment management. It serves as an essential toolkit for developers and power users who need to programmatically interact with graphical user interfaces, automate manual repetitive tasks, or capture visual data from their system. By bridging the gap between CLI-driven commands and the macOS Accessibility API, Peekaboo enables seamless control over applications, windows, menus, and system dialogs without requiring manual intervention.

• Full UI lifecycle management including app launching, focusing, resizing, moving, and application state control.

• Advanced capture capabilities with support for screen, window, and menu bar regions, including live video ingest and frame extraction.

• Robust interaction suite for precise mouse movements, drag-and-drop operations, gestures, and smart keyboard typing with configurable delays and profiles.

• Direct integration with macOS accessibility services and system menus, including dock items, menu bar extras, and global hotkeys.

• JSON-native scripting support using .peekaboo.json files, allowing complex workflows to be defined and executed reliably with --json output for piping.

• Snapshot-based targeting system using identifiers to track UI elements, combined with smart-wait logic for improved reliability in volatile UI environments.

• Users must grant Screen Recording and Accessibility permissions in System Settings for the tool to function correctly.

• It is highly recommended to use the see --annotate command to inspect IDs and map out target UI elements before building automation scripts.

• The tool is designed to work as a standalone CLI or as an integrated component within agentic workflows, such as the OpenClaw assistant ecosystem.

• Supports various capture engines like classic, cg, modern, and ScreenCaptureKit for different macOS versions and security contexts.

• Performance and reliability are optimized through a snapshot cache, which can be managed using the clean command to prune temporary files.