How nischaldawadi/hyprlust works
1. This repository is a desktop-environment dotfiles bundle, not an application codebase. The architecture centers on a Wayland session driven by Hyprland, with many sub-configurations and helper scripts composing the user experience.
2. The core runtime layer is Hyprland itself: hyprland.conf plus files under hypr/UserConfigs, hypr/configs, hypr/hypridle.conf, hypr/hyprlock.conf, and hypr/pyprland.toml. These define monitor layout, keybinds, window rules, startup apps, idle/lock behavior, and workspace behavior.
3. User interaction is mostly mediated through scripts in .config/hypr/scripts and .config/hypr/UserScripts. These scripts are the control plane for common desktop actions: brightness, volume, screenshots, lock screen, clipboard, wallpaper changes, keyboard layout switching, gaming mode, media controls, and utility launchers. Hyprland keybinds invoke these scripts directly.
4. The visual theming pipeline is a major subsystem. Wallpaper/state-driven colors are generated by wallust and matugen, then propagated into app themes via templates for Hyprland, Kitty, Rofi, Waybar, SwayNC, Zathura, Qt (qt5ct, qt6ct, Kvantum), GTK 2/3/4, Starship, and other tool-specific configs. The repo’s look-and-feel is therefore data-driven from the wallpaper/palette layer downward.
5. The launcher and menu layer is Rofi-based. Multiple Rofi configs exist for search, clipboard, emoji, wallpaper selection/effects, Zsh theme switching, Waybar style/layout selection, and beats/music menus. These are not isolated utilities; they are the UI entry points for many Hyprland scripts.
6. Waybar is the status and command surface for the desktop. The repo contains many Waybar layouts and styles, plus wallust-generated colors. This implies a modular bar architecture where layout, widget set, and theme are selected independently per monitor/profile.
7. Notifications and session chrome are handled by SwayNC and Wlogout. SwayNC has its own style sheets and wallust-generated colors; Wlogout provides the session/logout menu. These integrate with Hyprland as session-level UI components rather than standalone apps.
8. Media is a distinct subsystem. MPD provides the music backend (mpd.conf, playlists, database/logs), while mpDris2 exposes it to desktop controls. rmpc is the terminal client, and helper scripts in Hyprland and Rofi wrap playback controls. Video playback is handled through mpv with a heavy Lua script stack (uosc, sponsorblock, playlist manager, quality menu, thumbnails, etc.), showing a layered media-player customization.
9. Browser/app-specific customization is present for Spotify via Spicetify. The repo stores the extracted Spotify UI, custom apps, themes, and backup artifacts, which means Spotify is treated as a themable runtime with its own patching and extension layer. Similarly, Seanime, Upscayl, streamrip, and other apps keep their caches, logs, databases, and settings under .config, but those are runtime state, not source architecture.
10. Developer/editor tooling is also configured as part of the desktop stack. Neovim uses a LazyVim-style Lua config with plugin definitions, while Zsh and Starship define shell behavior and prompt theming. These sit alongside terminal apps like Kitty, Yazi, btop, fastfetch, and zathura to form the primary productivity environment.
11. There is a clear separation between source-like configuration and mutable state. The repo includes many persistent databases, caches, logs, and session files under app directories such as Seanime, MPD, Upscayl, Spotify/Spicetify, and yt-x. For architecture diagrams, these should be shown as local state stores attached to their respective apps, not as shared backend services.
12. Overall flow: wallpaper/theme selection feeds color generation, generated palettes propagate to desktop/app themes, Hyprland keybinds and scripts orchestrate behavior, and specialized apps (media, launcher, notifications, editor, music, browser tweaks) consume those configs. The repository’s main boundary is the user session itself: a themed, script-driven Linux desktop assembled from many independently configured clients.
Main entry points: hyprland.conf Hyprland · templates Theme templates · scripts Control scripts · mpd.conf MPD
Components 23
Session
Wayland session orchestration and Hyprland runtime
- Hyprland · Main Wayland session and window manager entrypoint
.config/hypr/hyprland.conf - User configs · Session settings, monitors, rules, startup apps, and keybinds
.config/hypr/UserConfigs - Core configs · Additional Hyprland settings and bind definitions
.config/hypr/configs - Pyprland · Hyprland plugin/runtime integrations
.config/hypr/pyprland.toml
Theming
Wallpaper-driven palette generation and desktop/app styling
- Wallpaper state · Current wallpaper and derived wallpaper-effects state
.config/hypr/wallpaper_effects - Wallust · Wallpaper-to-palette generation for desktop themes
.config/wallust/wallust.toml - Matugen · Theme token generation and template expansion
.config/matugen/config.toml - Theme templates · Shared templates that fan out colors into app-specific configs
.config/wallust/templates
Interaction
Launchers, menus, and input-driven desktop actions
- Control scripts · Hyprland action scripts for system controls and desktop behavior
.config/hypr/scripts - User scripts · User-facing scripts invoked from Hyprland and launchers
.config/hypr/UserScripts - Rofi · Launcher and menu entrypoints for desktop actions
.config/rofi/config.rasi
Status
Bars, notifications, and session chrome
Media
Music and video playback stack
- MPD · Music daemon, database, playlists, and logs
.config/mpd/mpd.conf - mpDris2 · Desktop control bridge for MPD playback
.config/mpDris2/mpDris2.conf - rmpc · Terminal MPD client and theme config
.config/rmpc/config.ron - mpv · Media player with a layered Lua script stack
.config/mpv/mpv.conf - Spicetify · Spotify UI extraction, themes, and custom apps
.config/spicetify/config-xpui.ini
Productivity
Terminal, editor, shell, and supporting apps
- Kitty · Terminal emulator theming and colors
.config/kitty/kitty.conf - Neovim · LazyVim-style editor configuration and plugins
.config/nvim/init.lua - Shell prompt · Zsh runtime and Starship prompt theming
.config/starship.toml - App state · Local caches, databases, and logs kept per application
.config/Seanime
Connections 31
- Wallpaper state → Wallust: feeds colors · Wallpaper selection drives palette extraction
- Wallpaper state → Matugen: feeds colors · Wallpaper state also informs token generation
- Wallust → Theme templates: renders · Wallust fills shared theme templates
- Matugen → Theme templates: renders · Matugen expands templates for multiple targets
- Theme templates → Hyprland: styles · Generated colors flow into Hyprland visuals
- Theme templates → Kitty: styles · Terminal colors are generated from the palette pipeline
- Theme templates → Rofi: styles · Launcher themes are palette-driven
- Theme templates → Waybar: styles · Waybar styling and colors are generated here
- Theme templates → SwayNC: styles · Notification styling is palette-driven
- Theme templates → Spicetify: styles · Spotify theme assets consume generated colors
- Theme templates → Shell prompt: styles · Prompt theming follows the same palette source
- Hyprland → User configs: includes · Main session file assembles user-level configs
- Hyprland → Core configs: includes · Core settings and bind definitions are split out
- Hyprland → Pyprland: integrates · Plugin/runtime extensions augment the session
- Hyprland → Control scripts: invokes · Keybinds and actions call control scripts
- Hyprland → User scripts: invokes · User scripts provide higher-level desktop actions
- Hyprland → Waybar: hosts · Waybar is part of the session chrome
- Hyprland → SwayNC: hosts · Notification center attaches to the desktop session
- Hyprland → Wlogout: hosts · Logout UI is launched from the session
- Rofi → Control scripts: launches · Rofi menus are entry points for action scripts
- Control scripts → Waybar: controls · Scripts switch bar layouts and styles
- Control scripts → Wlogout: opens · Session scripts launch logout/power UI
- Control scripts → MPD: controls · Media-control scripts target the MPD backend
- mpDris2 → MPD: bridges · Exposes MPD to desktop controls and notifications
- rmpc → MPD: clients · Terminal client talks to MPD
- mpv → Control scripts: controlled by · Playback helpers and keybinds wrap mpv behavior
- Spicetify → Wallust: themed by · Spotify theming is aligned with the palette pipeline
- Neovim → Shell prompt: paired with · Editor and shell define the productivity environment
- App state → Spicetify: stores state · Spotify runtime artifacts live beside the themed config
- App state → MPD: stores state · Music daemon databases and playlists are local state
- App state → mpv: stores state · Player state, scripts, and subtitles are local runtime data