Architecture
How the pieces start, talk to each other and share one set of colours.
Start-up
Login. The login screen starts uwsm start hyprland-uwsm.desktop. uwsm reads ~/.config/uwsm/env, so every
service sees the same environment (cursor, Qt platform, toolkit settings).
Hyprland reads hyprland.lua, which pulls in, in order: colors.lua (from the wallpaper), plugins.lua,
keys.lua (your Settings shortcuts), look.lua (Settings → Windows & Effects), hyprland-gui.lua (HyprMod, if
used) and finally user.lua.
User services start with the graphical session: quickshell (the whole shell), awww-daemon (wallpaper),
cliphist (clipboard history), hypridle (dim, lock, screen off, sleep on battery) and hyprpolkitagent
(password prompts).
At hyprland.start two small jobs run: hypr-plugins auto (rebuild plugins after a Hyprland update) and,
once after installing, setwall for the first wallpaper.
Who talks to whom
| From | To | How |
|---|---|---|
Keybinds in hyprland.lua | The shell | qs ipc call shell <function> |
| The shell | Hyprland | Quickshell's Hyprland module (workspaces, windows, monitors) and hyprctl |
| Settings → Windows & Effects | Hyprland | writes look.json → generates look.lua; Hyprland reloads required files by itself |
setwall | Everything coloured | awww img for the picture, then matugen renders every template and runs its reload hooks |
| Bar, Control Centre | System | NetworkManager, BlueZ, PipeWire, UPower and power-profiles-daemon over D-Bus |
One palette, many apps
matugen reads the wallpaper once and writes a template per target. Each target reloads itself:
| Target | File | Reload |
|---|---|---|
| Shell | ~/.local/state/quickshell/generated/colors.json | the shell watches the file |
| GTK 3 / 4 | gtk-3.0/colors.css, gtk-4.0/colors.css | theme name flipped to force a re-read |
| Qt | qt5ct, qt6ct, Kvantum/matugen | next app start |
| Ghostty | ghostty/themes/Matugen | SIGUSR2, live |
| Hyprland borders | hypr/colors.lua | hyprctl reload |
| Prompt, btop, cava | starship.toml, btop/themes, cava/config | next prompt / SIGUSR1 |
Why Quickshell
The shell is about 60 QML files instead of a bar, a launcher, a notification daemon and an OSD from four projects. One process means one look, one set of colours and one place for shortcuts, and panels can be created only while they are open.