Screen size, workspaces (* = shown, (n) = window count), focused window and how the user can watch.

Capture the agent desktop, or a region of it (x, y, width, height).

Use scale < 1 to save tokens; click coordinates are always full-scale screen pixels. workspace captures another workspace: the view switches there for the capture and then back (hidden workspaces have no pixels until shown).

Magnify a region (x, y, width, height) of the screen to read small text or icons.

The image is upscaled by factor (default: to about 1568px on the long side, at most 4x). Image pixel (px, py) is screen pixel (x + px / factor, y + py / factor).

Run a shell command inside the agent desktop's environment and return its output.

For short commands: xclip/xdotool, reading app logs, files under the agent's $HOME. It sees the agent desktop's display and D-Bus, not the user's. Use launch for GUI apps and anything long-running: this waits for the command, and kills it and everything it started after timeout seconds (max 300). stdin is empty.

Run a shell command on the agent desktop (e.g. 'xterm', 'firefox --new-instance').

The window opens on workspace (the view switches there first) or the current one. Waits up to wait_for_window seconds (max 60) for the new window, focuses it and reports it.

Sleep, e.g. to let an app finish loading before a screenshot. Max 30s.

Wait until nothing on screen has been redrawn for quiet_ms (or timeout seconds pass, max 60).

Each redrawn rectangle smaller than min_area square pixels (default about 20x20: blinking text cursors, small spinners) is ignored; min_area=0 counts every pixel.

Kill the agent desktop and every app on it, then start a fresh one.

All windows (or those on one workspace), topmost first, with ids for the window tools.

frame = the whole window on screen (title bar and borders included), content = the app's own area; both are (x,y widthxheight) in screen pixels.

Focus and raise a window (switching to its workspace and unminimizing it if needed).

Ask a window to close, as its close button would. The app may ask to confirm.

Apply an action to a window (default: the focused one).

kill disconnects the window's app from the display (XKillClient), which ends most apps immediately, and kills its process if that survives; use close_window first.

Place a window's frame (title bar and borders included) at (x, y) with this outer size.

Apps with size steps (terminals snap to character cells) or limits may end up a little smaller; the result reports the actual geometry.

Arrange the normal windows of a workspace (default: the shown one) side by side.

columns: next to each other; rows: stacked; grid: rows of up to ceil(sqrt(n)). Windows go in the order they were opened. Dialogs and minimized windows are left alone.

Show a workspace (numbered from 1). Windows on other workspaces are hidden, not closed.

Move a window (default: the focused one) to another workspace. The view stays where it is.

Change how many workspaces there are (1-32). Windows on removed ones move to the last remaining.

Move the agent's pointer to screen pixel (x, y).

Click at (x, y), or where the pointer is. count=2 double-clicks, 3 triple-clicks.

Press at (x1, y1), move to (x2, y2) in steps, release.

Scroll by wheel notches at (x, y) or the pointer. Negative down = up, negative right = left.

Type text into the focused window. Any Unicode works, independent of keyboard layout.

Newlines press Return and tabs press Tab.

Press key combos, space-separated: 'ctrl+l', 'Return', 'ctrl+shift+t alt+F4'.

Key names are X keysyms (Return, Tab, Escape, BackSpace, Up, F5, a, 1, ...).