What runs under the hood
Every backend is a native command, nothing more. The registry lives in backends.py — this table is generated from the same data.
+---------------------+----------+---------+--------+---------+---------+
| backend | platform | session | region | monitor | display |
+---------------------+----------+---------+--------+---------+---------+
| screencapture | macOS | — | yes | yes | yes |
| powershell | Windows | — | yes | yes | — |
| pwsh | Windows | — | yes | yes | — |
| grim | Linux | wayland | yes | — | yes |
| grimshot | Linux | wayland | — | — | — |
| scrot | Linux | x11 | yes | — | — |
| maim | Linux | x11 | yes | — | — |
| import | Linux | x11 | yes | — | — |
| gnome-screenshot | Linux | any | — | — | — |
| spectacle | Linux | any | — | yes | — |
| xfce4-screenshooter | Linux | x11 | — | — | — |
| flameshot | Linux | any | — | — | — |
+---------------------+----------+---------+--------+---------+---------+
region = -r/--region · monitor = -m/--monitor · display = --display · session "any" = works on both X11 and Wayland
From call to PNG
Positional arguments, a region object, and a temp file. That is the whole contract.
cli · library · mcp
│
▼
capture.py ─────── atomic temp file, size from the png header
│
│ CaptureRequest(region, monitor, display)
▼
backends.py ────── platform + session detection, best-first order
│
│ argv
▼
the OS tool ────── screencapture · powershell · grim · scrot · maim
import · gnome-screenshot · spectacle · flameshotHow one gets picked
In order, skipping anything that fails a step. A region request skips backends that cannot crop. Forcing --backend skips the search but still validates.
1 platform matches darwin | win32 | linux 2 session matches wayland vs x11 (linux only) 3 binary exists shutil.which(name) is not None 4 capabilities hold region / monitor / display requested 5 first match wins unless you pass --backend name
see the decision for yourself
$ screenagents --list-backendsok screencapture macOS built-in screencapture(1)ok grim Wayland grim (wlroots compositors)-- scrot X11 scrot (needs a x11 session (this is wayland))-- flameshot Flameshot (missing executable: flameshot)
Want it to fail loudly instead of fall back? --backend grim errors with the exact reason — see exit codes.