synui

synui

The Wayland compositor, on wlroots 0.20, rendering through scenefx 0.5's fx_renderer. Written for this system rather than adapted to it: it draws its own display, wallpaper, dock, cursor, sound and control panels, renders an optional CRT post-process pass, and holds live subscriptions to synguard's verdict feed and synapd's activity.

Five layouts — tiling, floating, monocle, AI and niri — with per-output workspaces, XWayland and layer-shell. What each one does: The Desktop → Layouts. Every shortcut: Keybindings.

If you want	Go to
The bar, widgets, desktop icons, layouts	The Desktop
Glass, blur, shadows, the CRT pass	Window Effects
Wallpapers, including Steam Workshop	Wallpapers
Cursors · event sounds	Cursor Themes · Sound Themes
Every keybinding	Keybindings
Working on the code	Development Notes

---

Start here

Super+C opens the control panel — the front door. It lists every shortcut, generated from the live bind table, so it cannot drift from the actual bindings, and every setting sits beside them. Super+/ is the same list as a search box. Tapping Super alone opens the start menu.

If you remember two keys, remember those.

---

What it does

Shell

The bar — a native quickshell bar, one per monitor, with per-monitor settings, a right-click menu and auto-hide. It replaced waybar, and the start button and menu now live in it. See The Desktop.

Dock — auto-hide with hover-slide and a reveal dwell, right-click context menu, runtime pin/unpin, and drag to any edge (vertical on left and right).

Desktop — optional ~/Desktop icons with drag-to-place, persistent placement and arrange by name/type/size/date; a right-click menu; and four optional widgets (visualiser, sysmon, big clock, quick-launch), all off by default.

Mixer — right-click the bar's volume module for per-device and per-application levels, drawn by the bar itself. See The Desktop.

System tray (SNI), clipboard history (Super+V), news reader (Super+R), and an ISO mounter that uses udisks2 and needs no root.

Look

Themes (Super+T) — SYNAPSE / Dark / XP / 95 plus six riced palettes, applied across synui's own chrome, the bar, GTK, Qt/KDE, the terminal (kitty, and foot where present) and Firefox.

Window effects — glass, backdrop blur, rounded corners, drop shadows with a shadow_spread knob, an optional glass_halo ring, and clip_csd_margin for clients that paint their own shadow. Plus the CRT pass (Super+E): scanline, curvature, aberration, glitch, and amber/green/white phosphor with bloom. Everything here is off by default. See Window Effects.

Wallpapers (Super+W) — built-in Synapse (static) and Matrix (animated GLES2 rain), a browser for ~/Pictures and friends, per-monitor choices, scaling modes on Tab, and Steam Workshop wallpapers through the optional linux-wallpaperengine package. See Wallpapers.

Cursor themes (Super+Shift+P) and event sounds (Super+S) — ten events, all silent until you turn them on.

Hardware

Display (Super+D) — per-output mode, position, scale, 10-bit colour, and HDR detected from the EDID rather than from the plane's bit depth. Monitor grid with aligned columns; night light is part of the output state.

Power (Super+P) — compositor-native dim, blank, lock and suspend, which retired swayidle entirely. Includes media idle-inhibit: it will not blank the screen while audio is playing. Explicit laptop lid policy, brightness keys, battery.

Lock screen (Super+L) and a graphical greeter over greetd IPC, drawn in-process and mirroring the lock screen.

AI and security

Neural overlay (Super+A) — live from synapd. Security feed — live from synguard. The AI layout asks synapd where windows should go and falls back to tiling when it cannot answer.

Task manager (Ctrl+Alt+Delete) — process table with a CPU/RAM/GPU overview and per-process VRAM through NVML, dlopen'd so no CUDA headers are needed to build.

Game mode (Super+G) — detects a fullscreen Xwayland client, stops synapd to free its VRAM, and holds off idle. The bar shows an indicator.

Screenshots and recording — Print and friends (Keybindings); Super+Shift+R records, to ~/Videos at a constant 60 fps. Capturing at a fixed rate rather than only when the screen changes is what keeps the file usable by a video editor — see Troubleshooting for the whole story, and Control panel ▸ Sound ▸ Record for editing for the switch that records an editable mezzanine instead.

And cat mode (Super+Shift+C) — a procedurally drawn cairo kitty that wanders your monitors on top of everything, because why not.

---

Config

~/.config/synui/synuirc, or /etc/synui/synuirc for the system-wide default. Monitor layout is separate, in outputs.conf, where primary=1 marks the primary output for Xwayland — which is what stops SDL games opening on the wrong monitor. Its x/y are taken verbatim; synui does not repack them into rows.

State files live beside it — wallpaper.state, wpengine.state, dock.state, power.state, filters.state, welcome.state, cursor.state, cursor.env, sounds.state, widgets.state, theme.json, layouts.state.

A state file wins over synuirc. That is deliberate: it is what makes a choice you made in a panel survive both a restart and a packaged config update. If an edit to synuirc appears to do nothing, a panel has already written that setting — change it in the panel, or delete the state file. Wallpapers is the one people meet first.

The file is synuirc, not synui.conf. Everything under that directory resolves through one helper, so XDG_CONFIG_HOME is honoured consistently.

Rebinding keys, and the bind = syntax: Keybindings → Rebinding.

---

Working on synui

The compositor-specific traps that cost real days — event-loop deadlocks, popup grabs, exclusiveZone ordering, stale swapchains, the seam rule — are in Development Notes → Compositor traps, alongside the cross-cutting ones.

Most rendering work is verified in a nested headless compositor rather than on a real seat, which has its own three non-negotiable rules (scenefx is GLES2-only so software rendering must be forced; synui-apply-theme has to be stubbed or a nested session re-themes the live desktop; and you must confirm which compositor you are talking to before trusting a result). Full recipe: Development Notes → Testing the compositor without a real seat.

Building and packaging: Building and Packaging. Roadmap: synui/ROADMAP.md.

---

See also: Keybindings, The Desktop, Window Effects, Architecture.