Peek

See and drive any Mac app — from your terminal or your AI agent.

Inspect any UI, click any button, fire any shortcut, drag any tab, type into any field, snap any window, hit-test any pixel. Peek does all of it with structured output — perfect for scripts and AI agents that need to know what just happened.

See it in action

A complete automation — discover, act, verify, capture — in five calls. Run it yourself with the macOS Calculator.

1. Discover — launch the app and get its window handle

peek launch --name Calculator --wait-for-window --format json
{"pid":12345,"windowID":4977,"windowTitle":"Calculator", ...}

--wait-for-window blocks until an AX-visible window appears and returns the windowID directly. Skip the usual follow-up peek apps call.

2. Inspect — find the element you want to drive

peek find --app Calculator --role Button --title 5 --limit 1 --format json
[{"role":"Button","description":"5","frame":{"x":902,"y":422,"width":48,"height":48}}]

Read-only check. --limit 1 stops at the first hit — a cheap existence test before committing to an action. --title matches AXTitle OR AXDescription, so labels and accessibility descriptions both resolve.

3. Act — press the button and capture what changed, atomically

peek action --app Calculator --do Press --role Button --title 5 --verify diff --format json
{
  "action": [{"role":"Button","description":"5", ...}],
  "diff": {
    "changed": [{"role":"StaticText","before":{"value":"‎0"},"after":{"value":"‎5"}}],
    "added":   [{"role":"Button","description":"Clear"}],
    "removed": [{"role":"Button","description":"All Clear"}]
  }
}

--verify diff snapshots the post-action tree and returns only the delta in the same call that pressed the button. No race window between acting and observing.

4. Screenshot the area — just the display

peek capture --app Calculator --output display.png --x 10 --y 86 --width 210 --height 42

--x --y --width --height crops in window-relative coordinates, so the same script works no matter where the user dragged the window. Drop straight into a test artifact or a PR comment.

5. Screenshot everything — the full window

peek capture --app Calculator --output calculator.png

Omit the crop flags for the whole window. Use the cropped shot for "did the display update?", the full shot for "here's the end state."

Install

Homebrew

brew install alexmx/tools/peek

Mise

mise use --global github:alexmx/peek

Requirements

• macOS 15.0 or later
• Accessibility permission for most commands
• Screen Recording permission for peek capture

Run peek doctor --prompt to check and request permissions.

More examples

# Hit-test: what's behind this pixel?
peek find --app Xcode --x 280 --y 50

# Filter by AX attribute, not just title (System Settings stores labels in `value`)
peek find --app "System Settings" --value "General"

# Read the menu bar and discover shortcuts
peek menu --app Safari --find "New Tab"

# Fire any shortcut at a specific app — ⌘-combos, F-keys, Escape, arrows
peek key --key s --modifiers cmd --app TextEdit

# Drag for reorder / drag-and-drop (positions from peek find)
peek drag --app Safari --from-x 420 --from-y 60 --to-x 220 --to-y 60

Command reference

All commands accept --format json (default for MCP) or --format toon (token-optimised, ~30-50% smaller). Most accept a target via --app NAME, --pid PID, or a positional <window-id> (from peek apps).

Discovery

Inspection

Interaction

Window-less system UI (Dock, Control Center, status-menu helpers) is addressable too — pass --app or --pid and find/tree/action/move scope to the app's AX root. These processes don't appear in peek apps.

Monitoring & System

MCP server

Peek runs as a stdio MCP server. Every CLI command is exposed as a peek_* tool (peek_click, peek_find, …) mirroring the CLI 1:1. Plus peek_wait (MCP-only) — polls for an element to appear, useful when waiting on UI you don't trigger directly (a dialog opens, a spinner vanishes).

peek mcp --setup   # prints config for Claude Code, Cursor, Codex CLI, etc.

Manual configuration:

{
  "mcpServers": {
    "peek": { "command": "peek", "args": ["mcp"] }
  }
}

Use with AI agents

A skill guide for agents driving peek via the CLI lives at skills/peek/SKILL.md. Install it with Skillman:

skillman install github.com/alexmx/peek

License

Released under the MIT License.