peekaboo

Automate macOS GUI tasks using AX-tree discovery with vision fallback.

15|1|Updated Feb 17, 2026
One-click install
npx skills add https://github.com/buildoak/fieldwork-skills --skill peekaboo-buildoak
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: peekaboo
Source: https://github.com/buildoak/fieldwork-skills/tree/main/skills/peekaboo
Command: npx skills add https://github.com/buildoak/fieldwork-skills --skill peekaboo-buildoak

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires jq, and includes scripts (resource) and references (resource) components.

What problem does it solve?

Automates macOS GUI tasks with an AX-first automation core and vision fallback to handle brittle UIs and complex workflows.

Core Features & Use Cases

  • AX discovery for native apps, dialogs, menus, and cross-app flows; vision fallback via UI-TARS for tough UIs.
  • FSM-based workflows with explicit recovery paths and bug-specific transitions.
  • Safe, sequential execution wrapper to ensure deterministic actions.

Quick Start

Run a health check, then perform a baseline see/interact/verify sequence to validate end-to-end automation.

Frequently Asked Questions about peekaboo

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I automate macOS GUI tasks reliably without UI elements breaking?

macOS GUI automation can be stabilized using an AX-first core with vision fallback. This approach discovers accessibility trees for native apps and dialogs, applying a finite-state machine to ensure deterministic, sequential execution and explicit failure recovery.

Can I automate system dialogs and file pickers on macOS using accessibility trees?

Yes, you can automate system dialogs and file pickers using AX-tree discovery. This method targets native macOS UI elements directly, enabling programmatic navigation and health checks for cross-app data flows without relying on brittle screen coordinates.

What is the best way to handle brittle macOS UI during cross-app automation workflows?

The best way to handle brittle macOS UI is combining an accessibility-tree-first core with vision fallback. A finite-state machine workflow manages explicit recovery paths and bug-specific transitions, ensuring safe sequential execution when UI elements shift.

Does macOS GUI automation work with complex workflows involving multiple native apps?

macOS GUI automation supports complex cross-app data flows by applying a finite-state machine workflow. It uses AX-tree discovery for native apps and vision fallback for tough UIs, delivering safe sequential execution with programmatic navigation.

Why does my macOS UI automation fail when encountering tough non-standard interfaces?

macOS UI automation often fails on non-standard interfaces lacking accessibility labels. A vision fallback mechanism addresses this by visually analyzing the UI, while a finite-state machine workflow provides explicit recovery paths to resume deterministic execution.

Do I need jq to run macOS GUI automation workflows with a finite-state machine?

Yes, you need jq installed to process JSON data structures within the macOS GUI automation workflows. It supports the finite-state machine logic and AX-tree discovery outputs required for deterministic, sequential execution and failure recovery.