Vercel Labs released agent-desktop, a cross-platform CLI and C library enabling AI agents to read and operate desktop applications via OS accessibility trees on macOS, Windows, and Linux (AT-SPI). The tool captures structured JSON snapshots containing element references (refs) for every actionable UI component, allowing agents to act on a ref — such as clicking @s8f3k2p9:e8 — then re-snapshot to verify state changes without pixel matching. Each CLI invocation runs in an isolated process; headless mode prohibits foreground activation and synthesized input, while a global --headed flag permits physical input. The snapshot output includes versioned envelopes with fields like snapshot_id, ref_count, window metadata, and a trimmed accessibility tree showing roles, names, ref_ids, and available_actions. Refs are bound to their originating snapshot; stale or ambiguous targets return STALE_REF or AMBIGUOUS_TARGET errors with candidate window IDs, requiring a fresh snapshot. Dense UIs support skeleton mapping (--skeleton --compact) and regional drilling via --root. The binary includes 60 commands across groups: Observe (snapshot, find, screenshot), Act (click, type, scroll, toggle), Keyboard/Mouse (press, drag, key-down), Apps/Windows (launch, list-windows, resize-window), Notifications, Clipboard, Wait, Sessions, and System. Platform parity varies: macOS and Windows support full click/type/mouse/screenshot/clipboard/window management; Linux uses AT-SPI for accessibility, X11 for mouse/window control, Wayland portals for screenshots, and requires wl-clipboard. A companion FFI library (libagent_desktop_ffi) allows in-process calls via C ABI (ad_init, ad_adapter_create), with platform-specific Cargo workspaces for building. Installation via npm (x64/ARM64 binaries), direct GitHub Release archives, or pending Homebrew/Scoop packages; macOS requires Accessibility permission grant. Documentation covers JSON contracts, error codes (retry disposition), skills for agent integration, and platform capability tables.
Read original
github-trending/rust