August 2026
linux-use reads the AT-SPI2 accessibility tree and acts on it: list apps and windows, enumerate interactive elements, click, type, send key combos, and read text back. No screenshots, no pixel coordinates, no LLM inside — your agent is the loop. One 154 KB static binary with no runtime dependencies.
The act command invokes a widget's own accessible action — no focus stealing, no pointer movement, and it works even when the window is completely hidden behind another window. Synthetic XTEST clicking is there as a fallback for widgets that expose no action.
References come in two kinds — by position in the widget tree, or by role and on-screen rectangle for widgets whose tree position cannot be proven. Every reference carries a fingerprint of its role and name. When the UI changes underneath one, you get exit code 83 and a suggestion to re-read the screen — instead of an action silently landing on the wrong widget. Elements whose identity cannot be proven are reported as unusable rather than emitted as a plausible guess.
The watch command streams real AT-SPI events as newline-delimited JSON, one line per event, with a resolved element reference. Filter by app, by role, or by event type; stop after exactly N events, after a time limit, or above a memory ceiling. Filtering to a single role took one sample run from 54 events down to the 6 that mattered.
Reads run as an AT-SPI collection query that matches server-side in one round trip, with the climb back to each match memoized. Measured across six applications, five are 1.1x to 5.9x faster than walking the tree with byte-identical results; the sixth cannot resolve every match, so the read is automatically re-run as a walk rather than returning an incomplete answer. The output always says which path it took.
A tree read that was cut short by a depth or node limit says so — in the JSON and on stderr. This came from a real bug: the old default depth silently returned zero text fields for a text editor, which would lead an agent to conclude the editor had none.
JSON on stdout, context on stderr, semantic exit codes, and typed errors that carry recoverable plus concrete suggestions. guide ships the whole operator manual inside the binary, and a warm-registry daemon keeps repeated calls fast. Follows the specs at cli-specs.intrane.fr.