Linux Setup

Linux setup

X11 — nothing to do

The X11 backend (XInput2 listener + XTest emitter) needs no setup script and no group membership. Layout switching goes through your DE's own mechanism, falling back to XKB group locking on bare window managers (i3, openbox, …).

Wayland — one script, once

The Wayland backend reads keyboards via evdev and types via uinput, which needs device access:

# The AppImage carries the script; PolterType's own error message
# names the path it is running from.
bash /path/to/mounted-appimage/usr/share/poltertype/scripts/setup-linux.sh

The script adds you to the input group and installs a udev rule for /dev/uinput. Log out and back in afterwards — group membership is granted at login. Half-applied state (group added, session old) is the most common "it doesn't work" cause; since 0.17.4 the script checks its own work and tells you which half is missing instead of printing "Done".

NixOS

Nothing above can be applied imperatively there — /etc/udev/rules.d is a read-only symlink into the Nix store, and a group added with usermod is dropped by the next rebuild. The script recognises NixOS and writes the declarative equivalent instead: it drops /etc/nixos/poltertype.nix (uinput, the two groups, and programs.appimage.binfmt — without which NixOS cannot exec the AppImage at all), adds one line to your imports, keeps a backup of configuration.nix, and stages the new file with git so a flake-based rebuild can see it. Then it is over to you:

sudo nixos-rebuild switch   # and log out and back in

Re-run the script afterwards and every line should read ✓.

Which desktops can switch the layout

Measured session by session, not inferred from what a desktop ships.

Works	Notes
Hyprland, KDE Plasma, GNOME, sway	Wayland
Xfce, LXQt, Cinnamon, i3, icewm, openbox, fluxbox	X11

Does not	Why
MATE	its settings daemon owns the xkb group and reports it inconsistently
labwc, Budgie (Wayland), Xfce (Wayland)	wlroots: no runtime layout API
niri, river	have an API; no backend yet

Where it cannot switch, PolterType says so at startup and leaves the word alone.

On 0.20.x and earlier, a machine that had ever run GNOME could stop correcting in the other desktops on it. GNOME keeps its layout list in dconf, a file in your home directory that outlives the session which wrote it — so i3, fluxbox, icewm, LXQt, openbox and Xfce/X11 all picked the gsettings mechanism, wrote a setting nothing there acts on, and declined every correction with "the desktop put the layout back before we could type" in the log. Fixed in 0.21.0: upgrading is the fix.

IBus and Fcitx5 are used only when the session names one as its input method (XMODIFIERS=@im=fcitx); a daemon merely running for CJK input is ignored.

Running behind keyd / kanata / kmonad

Everything works, with one honest caveat: the key gate (holding your keystrokes back for the few milliseconds a correction is being typed) stands down when a remapper proxies PolterType's own virtual keyboard — it re-checks before every correction and simply falls back to detect-and-repair. You lose nothing except protection against extremely fast typing straight through a correction.

To get the stronger behaviour back under keyd, exclude PolterType's virtual device in your keyd config — the exact one-liner is in docs/PERMISSIONS.md.

Starting at login

"Start automatically when I sign in" installs a systemd user service wanted by graphical-session.target. GNOME, KDE, Xfce and anything launched through uwsm reach that target on their own and need nothing.

A bare Hyprland / Sway / river session reaches neither that target nor ~/.config/autostart, so autostart needs one five-line wiring, once — a session target of your own that pulls in the standard one, started from your compositor config after the environment is published. The recipe is in docs/PERMISSIONS.md, and PolterType writes a line in the log when it installs the unit into a session that will never reach it.

What renders where

• The spelling-suggestions tooltip probes layer-shell, then X11, then gives up — so it draws on wlroots compositors and KWin directly, and on GNOME Wayland through XWayland. A Wayland session with neither is the remaining gap (help wanted).
• Per-app features (skip list, per-app wordlist profiles, apps = scoping on smart commands) need a focus tracker, which exists on Hyprland and X11 — on other Wayland compositors they do nothing.