Skip to Content
MvpDots

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

FromToHow
Keybinds in hyprland.luaThe shellqs ipc call shell <function>
The shellHyprlandQuickshell's Hyprland module (workspaces, windows, monitors) and hyprctl
Settings → Windows & EffectsHyprlandwrites look.json → generates look.lua; Hyprland reloads required files by itself
setwallEverything colouredawww img for the picture, then matugen renders every template and runs its reload hooks
Bar, Control CentreSystemNetworkManager, 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:

TargetFileReload
Shell~/.local/state/quickshell/generated/colors.jsonthe shell watches the file
GTK 3 / 4gtk-3.0/colors.css, gtk-4.0/colors.csstheme name flipped to force a re-read
Qtqt5ct, qt6ct, Kvantum/matugennext app start
Ghosttyghostty/themes/MatugenSIGUSR2, live
Hyprland bordershypr/colors.luahyprctl reload
Prompt, btop, cavastarship.toml, btop/themes, cava/confignext 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.

On this page