agent-desktop

agent-desktop

agent-desktop is a CLI that reads and operates desktop apps through the OS accessibility tree. Every command prints one JSON envelope (ok, data or error). It is a tool, not an agent: the observe, act and verify loop runs in you.

Shell syntax

Examples use a POSIX shell. In PowerShell, quote every ref ('@s8f3k2p9:e1'), because a bare @token is the splatting operator. Use $env:NAME = 'value' instead of export, and | ConvertFrom-Json instead of $(...) and jq. The Windows skill has the PowerShell forms.

First run

1. Run agent-desktop status. It reports the platform, permissions and supported_surfaces.
2. Run agent-desktop skills get platform. It loads the skill for the OS the binary runs on (macOS, Windows or Linux).
3. For flags and syntax, run agent-desktop <command> --help. This skill does not repeat flag lists.

The loop

Use find when you know the role or exact name. Otherwise map the app first and drill into one region.

agent-desktop snapshot --skeleton --app "Notes" -i --compact   # shallow map, children_count on cut branches
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # drill into one region
agent-desktop click @s8f3k2p9:e12                              # act on a qualified ref
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # verify: re-read the same region

• A small app needs no skeleton. Take a full snapshot -i.
• -i keeps interactive nodes only, so a row's static-text label is dropped. To tell which row a repeated button belongs to, drill that row's container with --root and leave out -i. On Windows and Linux that reads the row but does not make its button actionable: a button repeated in other rows is a twin in the window and its ref is refused (see Refs).
• A --root drill adds its refs to the same snapshot id. Refs outside the drilled subtree, and the drilled root itself, stay valid; refs that were already inside it are replaced, so an old ref there returns STALE_REF.
• Never skeleton a surface (--surface menu, sheet, alert). A surface is already focused.
• An action that opens a menu, sheet or alert lists it in data.surfaces. Target that overlay next.
• After an async step, use wait (see commands-system.md). A fixed sleep is a race.