# Off-Workspace Windows and Captures

Applies to: `**/*` (any task that opens a window or takes a screenshot on the user's live desktop)

Never open a window or take a screenshot on the user's active workspace. When
visual verification needs a real window on the user's live desktop, keep it off
the workspace they're working in. An agent doing its own visual verification
shouldn't hijack the desktop the user is actively using.

The principle is environment-general: don't commandeer the user's active
workspace for agent-side visual work. The recipe below is the Hyprland/Wayland
implementation; other environments implement the same principle with their own
off-screen mechanism.

## Captures for your own verification

Render and grab the window off the user's physical screen, then tear it down. On
Hyprland this is a virtual headless output, verified non-disruptive on ratio
2026-07-06 — the physical monitor stayed on its workspace, focused, throughout:

```sh
hyprctl output create headless                          # virtual output on its own workspace
setsid <app> >/tmp/x.log 2>&1 </dev/null &
addr=$(hyprctl -j clients | python3 -c 'import json,sys; print(next((c["address"] for c in json.load(sys.stdin) if c.get("class")=="<CLASS>"), ""))')
hyprctl dispatch movetoworkspacesilent "<ws-on-headless>,address:$addr"   # silent = keeps the user's focus
grim -o HEADLESS-<n> /tmp/shot.png                       # capture the virtual output only
pkill -f '<app>$'; hyprctl output remove HEADLESS-<n>    # tear down, restore the display
```

Key constraint: `grim` captures a *visible output*, so a window merely parked on
another Hyprland workspace can't be screenshotted — it must render on the
headless (or another real) output. That's why a headless output, not just
"another workspace," is the tool for self-captures. A nested compositor
(weston/cage/sway) is the alternative on non-Hyprland Wayland or when a headless
output isn't available; it needs the compositor installed.

## Showing the user something

Open it on a *separate* real workspace and tell them which one, so it never
grabs their active workspace. They switch when ready. Craig's viewer preference
is `imv`; launch it through the compositor (`hyprctl dispatch exec "imv
<files>"`) so it survives the agent's shell rather than a bare `&` job that gets
reaped.

## Always clean up

Close the window and remove any headless output afterward. Verify the user's
display is restored: physical monitor back to its workspace, no orphan
processes.

## Related

- `verification.md` — this is part of how visual verification is done without
  disrupting the user.
- `interaction.md` — the broader "don't disrupt the user's active work" concern.
- `emacs.md` — the screenshot note for Emacs changes uses the same off-screen
  capture approach.