Skip to main content

​
Overview

The snapshot command captures the accessibility tree of an application with configurable options to control what elements are included and how the tree is structured. 
agent-desktop snapshot [OPTIONS]

​
Available Options

​
--app
string
Filter to a specific application by nameDefault: focused app
agent-desktop snapshot --app Safari
​
--window-id
string
Filter to a specific window by ID (from list-windows)
agent-desktop snapshot --window-id w-4521
​
-i / --interactive-only
boolean
Only include interactive elements in the treeDefault: falseInteractive elements include: buttons, text fields, checkboxes, links, menu items, tabs, sliders, combo boxes, tree items, cells, radio buttons, and switches.
agent-desktop snapshot --app Finder -i
​
--compact
boolean
Omit empty structural nodes to reduce tree sizeDefault: falseCollapses single-child unnamed nodes to reduce tree depth without losing interactive elements.
agent-desktop snapshot --compact
​
--include-bounds
boolean
Include pixel bounds (x, y, width, height) for each elementDefault: false
agent-desktop snapshot --include-bounds
​
--max-depth
number
Maximum tree depth to traverseDefault: 10Limits how deep the accessibility tree traversal will go. Lower values improve performance for complex UIs.
agent-desktop snapshot --max-depth 5
​
--surface
enum
Type of UI surface to snapshotDefault: windowOptions: window, focused, menu, menubar, sheet, popover, alert
agent-desktop snapshot --surface menu

​
Common Patterns

​
AI Agent Workflow

For optimal LLM performance, use interactive-only mode to reduce tree size: 
agent-desktop snapshot --app Finder -i

​
Capture Open Menu

Snapshot the currently open context menu or dropdown: 
agent-desktop snapshot --surface menu

​
Focused Application

Snapshot the currently focused app without specifying the name: 
agent-desktop snapshot -i

​
Performance Optimization

For large applications, combine flags to minimize output: 
agent-desktop snapshot --app Xcode -i --compact --max-depth 8

​
Output Format

All snapshots return structured JSON with element refs: 
{
  "version": "1.0",
  "ok": true,
  "command": "snapshot",
  "data": {
    "app": "Finder",
    "window": {
      "id": "w-4521",
      "title": "Documents"
    },
    "ref_count": 14,
    "tree": {
      "role": "window",
      "name": "Documents",
      "children": [
        {
          "ref": "@e1",
          "role": "button",
          "name": "Back"
        }
      ]
    }
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us