test-native - nested compositor + in-app probes
Goal: $ARGUMENTS
Two tools, used together or alone:
- A nested sway gives a real Wayland session with workspaces, focus and
frame callbacks, on any host (X11 desktop, Wayland desktop, or no display at
all), with scripted mouse/keyboard and screenshots. It is not a substitute
for GNOME/KDE-specific behavior (portals, KWin, mutter); for those use the
VMs in AGENTS.md ("Test VMs").
- Probes injected into the app measure what no log shows (frames,
observers, focus, timers, IPC shapes) and let several candidate fixes ship
in ONE debug build, switched by environment variables, so each variant is a
relaunch, not a rebuild.
Read /linux for the session/DE routing the launcher does; this skill is
about producing those sessions and reading the app from inside.
1. Nested sway
sway is packaged everywhere (sway; grim for screenshots and wtype for
typing are small extras worth installing). Pick the backend by host:
| Host | Start | Notes |
|---|
| X11 desktop (XFCE, i3, ...) | WLR_BACKENDS=x11 sway | a 1024x768 window; resize with swaymsg output X11-1 resolution 1600x1000 |
| Wayland desktop (KDE, GNOME, sway) | WLR_BACKENDS=wayland sway | a nested window inside the host compositor |
| none / CI | WLR_BACKENDS=headless WLR_LIBINPUT_NO_DEVICES=1 WLR_RENDERER=pixman sway | no window; screenshots via grim |
Always start it with a minimal config (-c) so the host's ~/.config/sway
bindings do not interfere, and talk to it through its own socket:
printf 'output * resolution 1600x1000\ndefault_border none\n' > /tmp/sway-test.conf
WLR_BACKENDS=x11 sway -c /tmp/sway-test.conf &
export SWAYSOCK=$(ls -t /run/user/$(id -u)/sway-ipc.*.sock | head -1)
swaymsg -t get_outputs | jq -r '.[].name' # X11-1 / HEADLESS-1 / WL-1
ls /run/user/$(id -u)/wayland-* # the nested display, e.g. wayland-1
-c replaces ~/.config/sway/config entirely, so host bindings and outputs
never apply. The nested instance also starts its own XWayland (:1 when the
host owns :0); check with ss -xlp | grep X11-unix.
Launch the app INTO the nested session
A plain claude-desktop inherits the host's XDG_SESSION_TYPE/DISPLAY and
opens on the host desktop. Set the session variables explicitly; the launcher
tests XDG_SESSION_TYPE first:
# native Wayland, sway routing
swaymsg exec 'env -u DISPLAY WAYLAND_DISPLAY=wayland-1 XDG_SESSION_TYPE=wayland XDG_CURRENT_DESKTOP=sway claude-desktop'
# XWayland comparison (same compositor, X11 code path)
swaymsg exec 'env DISPLAY=:1 WAYLAND_DISPLAY=wayland-1 XDG_SESSION_TYPE=wayland CLAUDE_USE_XWAYLAND=1 claude-desktop'
# pretend to be another desktop for the launcher's routing (CU bridges, tray, portals)
... XDG_CURRENT_DESKTOP=KDE ... # see /linux for what each value changes
Only one instance per profile runs at a time: quit the host's Claude first
(pkill -f '^/usr/lib/claude-desktop/claude --enable', wait for the process
to go). Confirm where it landed: swaymsg -t get_tree | jq -c '.. | objects | select(.pid?) | {id,name,shell}' lists the app's windows with xdg_shell
(native) or xwayland. Confirm the ozone platform with pgrep -af claude | grep -o 'ozone-platform=[a-z]*'.
--remote-debugging-port and other debugging switches make the app refuse
to start; DevTools come from developer_settings.json instead (section 2).
Windows and workspaces
swaymsg '[title="^Test$"] move container to workspace 2'; swaymsg workspace 2 # hide everything else
swaymsg '[title="^Claude$"] focus'
swaymsg '[title="^Test$"] floating enable, resize set 1400 850, move position 50 60'
swaymsg -t get_workspaces | jq -c '.[] | {name,visible}'
A window on a non-visible workspace gets no frame callbacks - that is the
Wayland behavior sway, GNOME and KDE share and the reason native-Wayland
reports differ from X11 (#280).
Input
Mouse: sway's own seat, in layout coordinates - this reaches the app exactly
like a real pointer (xdotool clicks on an X11 host only move focus):
clk() { swaymsg -q "seat - cursor set $1 $2"; sleep 0.2; swaymsg -q "seat - cursor press button1"; sleep 0.1; swaymsg -q "seat - cursor release button1"; }
clk 1100 976
Keyboard: wtype (virtual-keyboard protocol, works on every host backend):
WAYLAND_DISPLAY=wayland-1 wtype -M ctrl -M alt i -m alt -m ctrl # chord
WAYLAND_DISPLAY=wayland-1 wtype -d 15 "$(cat snippet.js)" # text, 15 ms per key
If only xdotool is available (X11 host): match layouts first
(swaymsg input type:keyboard xkb_layout de to whatever setxkbmap -query
says), verify focus before every key (xdotool getwindowfocus getwindowname must be the sway window AND swaymsg -t get_tree | jq '.. | objects | select(.focused==true) | .name' the intended app window), never
click to focus, and screenshot before pressing Enter. Text that lands in the
chat composer gets SENT as a prompt to a Code session. Known oddity: single
letters can be swallowed on the X11 backend; wtype does not have it. The
host clipboard does not reach the nested session (XWayland's bridge did not
deliver to Chromium); do not plan on Ctrl+V.
Screenshots
WAYLAND_DISPLAY=wayland-1 grim shot.png # any backend, needs grim
import -window "$(xwininfo -root -tree | awk '/wlroots - X11-1/{print $1}')" shot.png # X11 host fallback
Crop with -crop WxH+X+Y +repage (ImageMagick) and read the image, or probe
a pixel region numerically for loops:
import -window $W -crop 200x150+940+780 +repage -colorspace gray -format '%[fx:mean]' info:.
Caveats
- Rendering is software (pixman/llvmpipe) - CPU numbers are not representative
of a GPU desktop; compare variants against each other, not against the host.
- The nested sway is sway, not the reporter's compositor. KWin/mutter-specific
behavior (portals, tiling, activation) needs the VMs.
- Keep the user's hands off the window while a scripted loop runs, and say so;
two sets of clicks produce garbage results.
2. Probes inside the Electron client
Where output goes
| From | Call | Lands in |
|---|
| main process | globalThis.__cdbDiag("[tag] ...") (exists after upstream's ready; queue before that - see js/popout_frames_main.js) | ~/.config/Claude/logs/claude-patches.log |
| main view (renderer) | console.warn/info/error("[tag] ...") | ~/.config/Claude/logs/claude.ai-web.log |
| CLI child | logs/custom-models.log style files | see AGENTS.md "Logs" |
3P mode uses ~/.config/Claude-3p/; profiles add -<name>.
DevTools without a rebuild
~/.config/Claude/developer_settings.json -> {"allowDevTools": true}
(or the Extra -> Community Features "Developer tools" row), then
Ctrl+Alt+I on the focused window (undocked). Upstream re-reads the file
on every press. Limits inside the console: the page CSP blocks eval and
dynamic import of fetched code, XHR to localhost needs CORS; type or paste
the code itself. For anything longer than a line, prefer the debug patch.
The debug-patch recipe (one build, many variants)
Copy the shape of patches/linux/fix_popout_menus_wayland.nim +
js/popout_frames_main.js + js/popout_frames_page.js:
- A head-injected main module (
"use strict" anchor with the prepend
fallback) that registers app.on("web-contents-created") ->
wc.on("dom-ready") -> wc.executeJavaScript(PAGE_SRC) for the main-view
origins (https://claude.ai/..., app://localhost/... minus
setup-desktop-3p). executeJavaScript is not subject to the page CSP.
- The page script measures and logs every N seconds (template:
reference/probe.js): real requestAnimationFrame cadence, ResizeObserver
latency, document.visibilityState, hasFocus(), plus the counters of
whatever shim is under test.
- Candidate fixes are gated by
process.env.CDB_<FEATURE>_* read in the
main module and passed to the page as a JSON config (replace the
placeholder with split/join, not replace, if the placeholder string
also appears in a comment). Each variant is then a relaunch with different
env vars; the user installs once.
- Bump
EXPECTED_PATCH_COUNT, build with ./scripts/build-local.sh, let the
user install, relaunch into the nested session, read the two logs.
- Strip the probe and the losing variant before the real patch ships;
keep an env escape hatch for the winner if it is cheap.
Remember what the 1P main view is: remote claude.ai code. A patch on
resources/ion-dist only reaches 3P mode (app://localhost); run-time
injection reaches both.
Reading the data
Baseline first (both windows visible), then the condition under test, then
the control (e.g. XWayland). A result is a before/after pair in the same log
with timestamps, not a single number. Quote the lines in the report.