wait

Pause execution for a fixed duration, or block until a UI condition is met (element appears, window opens, text appears, menu opens/closes, or notification arrives).

Usage

# Fixed duration
agent-desktop wait <MS>

# Wait for condition
agent-desktop wait --element <ref> [--timeout MS]
agent-desktop wait --window <title> [--timeout MS]
agent-desktop wait --text <text> [--app APP] [--timeout MS]
agent-desktop wait --menu [--app APP] [--timeout MS]
agent-desktop wait --menu-closed [--app APP] [--timeout MS]
agent-desktop wait --notification [--app APP] [--text TEXT] [--timeout MS]

Parameters

number

Milliseconds to pause. If provided, all other options are ignored.

agent-desktop wait 500  # pause 500ms

--element

string

Block until this element ref appears in the accessibility tree. Polls every 100ms.

agent-desktop wait --element @e5 --timeout 5000

--window

string

Block until a window with this title (partial match) appears. Polls every 100ms.

agent-desktop wait --window "Save As" --timeout 10000

--text

string

Block until this text appears in the app’s accessibility tree (case-insensitive). Polls every 200ms.

agent-desktop wait --text "Loading complete" --app Safari --timeout 30000

Block until a context menu is open. Polls every 100ms.

agent-desktop wait --menu --timeout 3000

Block until the context menu is dismissed. Polls every 100ms.

agent-desktop wait --menu-closed --timeout 3000

--notification

boolean

Block until a new notification arrives. Polls every 500ms.

agent-desktop wait --notification --timeout 60000

--app

string

Scope element, text, menu, or notification waits to this application.

agent-desktop wait --text "Done" --app TextEdit

--timeout

number

default:"30000"

Timeout in milliseconds for condition waits. Defaults to 30000ms (30 seconds).

agent-desktop wait --element @e5 --timeout 10000

Response

Fixed Duration Wait

waited_ms

number

required

The number of milliseconds waited

Element Wait

found

boolean

required

Always true if element was found before timeout

ref

string

required

The element ref that was found

elapsed_ms

number

required

Time in milliseconds until element appeared

Window Wait

found

boolean

required

Always true if window was found before timeout

window

object

required

The window object that matched

Show window object

string

Window ID

title

string

Window title

app_name

string

Application name

elapsed_ms

number

required

Time in milliseconds until window appeared

Text Wait

found

boolean

required

Always true if text was found before timeout

text

string

required

The text that was searched for

ref

string

Element ref where the text was found (if element has a ref)

role

string

required

Role of the element containing the text

elapsed_ms

number

required

Time in milliseconds until text appeared

found

boolean

required

Always true if menu condition was met before timeout

elapsed_ms

number

required

Time in milliseconds until menu opened/closed

Notification Wait

condition

string

required

Always "notification"

matched

boolean

required

Always true if a new notification arrived

notification

object

required

The notification that arrived

Show notification object

index

number

Notification index

app_name

string

App that sent the notification

title

string

Notification title

body

string

Notification body

elapsed_ms

number

required

Time in milliseconds until notification arrived

Examples

Fixed Duration

agent-desktop wait 1000

{
  "version": "1.0",
  "ok": true,
  "command": "wait",
  "data": {
    "waited_ms": 1000
  }
}

Wait for Element

agent-desktop wait --element @e5 --timeout 5000

{
  "version": "1.0",
  "ok": true,
  "command": "wait",
  "data": {
    "found": true,
    "ref": "@e5",
    "elapsed_ms": 1234
  }
}

Wait for Window

agent-desktop wait --window "Save As" --timeout 10000

{
  "version": "1.0",
  "ok": true,
  "command": "wait",
  "data": {
    "found": true,
    "window": {
      "id": "w-1234",
      "title": "Save As",
      "app_name": "TextEdit"
    },
    "elapsed_ms": 2345
  }
}

Wait for Text

agent-desktop wait --text "Loading complete" --app Safari

{
  "version": "1.0",
  "ok": true,
  "command": "wait",
  "data": {
    "found": true,
    "text": "Loading complete",
    "ref": "@e12",
    "role": "static_text",
    "elapsed_ms": 3456
  }
}

agent-desktop wait --menu --timeout 3000

{
  "version": "1.0",
  "ok": true,
  "command": "wait",
  "data": {
    "found": true,
    "elapsed_ms": 450
  }
}

Wait for Notification

agent-desktop wait --notification --app Slack --timeout 60000

{
  "version": "1.0",
  "ok": true,
  "command": "wait",
  "data": {
    "condition": "notification",
    "matched": true,
    "notification": {
      "index": 2,
      "app_name": "Slack",
      "title": "#engineering",
      "body": "New message"
    },
    "elapsed_ms": 15234
  }
}

Use Cases

Wait Between Actions

Pause to let UI settle:

agent-desktop click @e3
agent-desktop wait 500
agent-desktop snapshot -i

Wait for Dialog

Wait for a Save dialog to appear:

agent-desktop press cmd+s
agent-desktop wait --window "Save" --timeout 5000
agent-desktop snapshot -i

Wait for Loading

Wait for a loading indicator to disappear:

agent-desktop wait --text "Loading complete" --app Safari

Wait for Menu

Wait for Notification

Wait for a deployment notification:

agent-desktop wait --notification --text "deployment complete" --timeout 300000

Wait Conditions

Condition	Poll Interval	Use Case
`ms`	N/A	Fixed pause
`--element`	100ms	Element appears in tree
`--window`	100ms	Window opens
`--text`	200ms	Text appears anywhere
`--menu`	100ms	Context menu opens
`--menu-closed`	100ms	Context menu closes
`--notification`	500ms	New notification arrives

Error Handling

Common error codes:

TIMEOUT: Condition not met within timeout period
INVALID_ARGS: No valid wait condition provided
STALE_REF: Element ref in --element is not in the current refmap

{
  "version": "1.0",
  "ok": false,
  "command": "wait",
  "error": {
    "code": "TIMEOUT",
    "message": "Element @e5 not found within 5000ms",
    "suggestion": "Increase --timeout or verify element will appear"
  }
}

Notes

Fixed duration waits (wait <MS>) are precise and use std::thread::sleep
Condition waits poll at fixed intervals and may overshoot slightly
Text matching is case-insensitive and checks name, value, title, and description fields
Window title matching is a partial substring match
Notification waits detect new notifications only (compares against baseline)
Menu waits check for any open context menu in the specified app (or focused app)

snapshot - Capture UI state after waiting
list-notifications - List notifications instead of waiting
list-windows - List windows instead of waiting

Observation Commands

Interaction Commands

Keyboard Commands

Mouse Commands

App & Window Commands

Notification Commands

Clipboard Commands

Wait Commands

System Commands

Batch Commands

Usage

Parameters

Response

Fixed Duration Wait

Element Wait

Window Wait

Text Wait

Menu Wait

Notification Wait

Examples

Fixed Duration

Wait for Element

Wait for Window

Wait for Text

Wait for Menu

Wait for Notification

Use Cases

Wait Conditions

Error Handling

Notes

Build docs developers (and LLMs) love

Observation Commands

Interaction Commands

Keyboard Commands

Mouse Commands

App & Window Commands

Notification Commands

Clipboard Commands

Wait Commands

System Commands

Batch Commands

​Usage

​Parameters

​Response

​Fixed Duration Wait

​Element Wait

​Window Wait

​Text Wait

​Menu Wait

​Notification Wait

​Examples

​Fixed Duration

​Wait for Element

​Wait for Window

​Wait for Text

​Wait for Menu

​Wait for Notification

​Use Cases

​Wait Conditions

​Error Handling

​Notes

​Related Commands

Build docs developers (and LLMs) love

Usage

Parameters

Response

Fixed Duration Wait

Element Wait

Window Wait

Text Wait

Menu Wait

Notification Wait

Examples

Fixed Duration

Wait for Element

Wait for Window

Wait for Text

Wait for Menu

Wait for Notification

Use Cases

Wait Conditions

Error Handling

Notes

Related Commands