diff options
Diffstat (limited to 'claude-rules')
| -rw-r--r-- | claude-rules/desktop-capture.md | 57 | ||||
| -rw-r--r-- | claude-rules/verification.md | 2 |
2 files changed, 59 insertions, 0 deletions
diff --git a/claude-rules/desktop-capture.md b/claude-rules/desktop-capture.md new file mode 100644 index 0000000..0051c4d --- /dev/null +++ b/claude-rules/desktop-capture.md @@ -0,0 +1,57 @@ +# 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. diff --git a/claude-rules/verification.md b/claude-rules/verification.md index 26d05b5..2c2088e 100644 --- a/claude-rules/verification.md +++ b/claude-rules/verification.md @@ -68,6 +68,8 @@ Do not let an unverifiable check vanish into a confident summary. State it plain Some checks can only be run by the user: interactive UI a script can't drive, a live external service, visual rendering (colors, layout, faces), a real device, or anything where the verification *is* a human looking at the result. When the gap needs the user's hands or eyes — not just a command they could paste — don't bury the steps in prose. Write them as a structured, runnable checklist in the project's task file. +When *you* need a window on the user's live desktop to verify something visually — render a panel, grab a screenshot — keep it off the workspace they're actively using. Capture on an off-screen output and tear it down; when showing the user something, open it on a separate workspace and name it. See `desktop-capture.md` for the rule and the Hyprland recipe. + Create (or append to) a single parent task named **"Manual testing and validation"** in the project's todo file (`todo.org`, or the project's equivalent). Under it, write **one org sub-header per test**: - **Title** — descriptive, naming the behavior under test (not "test 1"). |