screens

Images, terminals and desktops

Agents make and inspect a lot of pictures: screenshots, renders, diagrams, emulator frames. Agent Utils shows them inline in the terminal, keeps them in durable archives, puts them into the model's context only when asked, and gives agents displays, emulators and VMs of their own to look at.

A gallery in the terminal

The kitty image preview is a persistent widget in the Pi session that draws images with the kitty graphics protocol: above or below the editor, or in a side panel sized to the image. Agents add images, folders or live screenshot streams; you page through them with /image-next, /image-prev and /image-hide.

Tool	Does
`kitty_image_preview_add`, `_add_folder`	Show an image, or a sorted series from a folder
`kitty_image_preview_capture`	Take a desktop screenshot with Tendril and show it
`kitty_image_preview_stream_start`	A live, low-resolution screenshot stream using two temporary files, so frames never pile up on disk or in context
`kitty_image_preview_playwright_start`	Mirror a Playwright browser while the agent keeps working from the DOM alone
`kitty_image_preview_share_current`	Put the selected image into the model's context, on purpose
`_show`, `_animate`, `_cycle`, `_status`	Navigate, animate a series, cycle on a timer, inspect

It works through tmux, SSH and terminal multiplexers. Under tmux it uses Unicode placeholders, so images stay anchored to their cells and scroll with the pane. Each image's bytes are uploaded once, and redraws only re-place it. Cleanup deletes only the image ids it created, never every image on the terminal. Any still image can be described by a vision model with describe: true, as text metadata.

Local by defaultPreviews, galleries and streams stay on your screen. An image enters the model's context, and the session's durable history, only through an explicit share. That keeps context small and private screens private.

Shared images and recovery

Every image an agent shares is copied into a durable per-machine archive under ~/.local/state/agent-utils, with a private sidecar recording its provenance and checksum, independent of any session. ag image gathers these archives across machines into one gallery (see Fleet).
If a provider rejects the latest image with HTTP 413, the image is too large. Agent Utils makes an exact half-width, half-height copy, replaces just that attachment in future context with a note giving the path, and retries once.

Desktops, phones and VMs

Tools	For
`tendril_pi_capture`, `_describe`, `_stream`	Capture any window or display through Tendril, locally or on another machine, straight into context
`capture_macos_screenshot`, `open_macos_app`	On macOS: share a crosshair-selected screenshot, or open an app in the background on the display you are not using
`android_emulator_screenshot`, `_stream`	Show an emulator or device in Pi through adb; `android_cli_*` installs and updates the SDK, after confirmation
`xvfb_ensure`, `xvfb_stop`, `xvfb_status`	An opt-in virtual X display on a headless machine, refusing to override a real one and torn down with the session
`firecracker_vm_*`	Prepare, start, inspect and stop Firecracker microVMs that expose browsers or services for Tendril to drive

Editor chrome

/gfx drives Pi's graphics effects and themes. Editor chips move the model, effort, MCP, cost, context, directory, branch and diff into Powerline-style chips around the editor, collapsing gracefully on narrow terminals. /eink switches a tablet or e-ink screen to a greyscale theme with static chrome and no animation, and /eink off puts everything back.