How caelestia-dots/shell works
Purpose and startup
Caelestia Shell is a Linux desktop shell implemented in QML for Quickshell and designed around the Hyprland compositor. The Quickshell configuration entry point is shell.qml; it composes persistent shell surfaces, services, and interaction modules. Users start it through the external caelestia CLI or Quickshell (qs -c caelestia).
Core build/install integration is CMake-based: CMakeLists.txt builds the native QML plugin and installs the QML configuration; Nix and Home Manager packaging live in flake.nix and nix/hm-module.nix.
Root composition, state, and shared UI
shell.qml is the root coordinator. It loads shared services and feature modules; module wrappers own their windows/surfaces and expose open/close state.
Shared QML primitives separate visual consistency from feature logic:
• components/ScreenState.qml and components/StateLayer.qml support per-screen/stateful composition.
• components/containers/StyledWindow.qml provides common window behavior.
• components/Anim.qml and components/StyledText.qml centralize animated Material-style presentation.
services/ShellState.qml is the likely cross-module shell-state boundary, while modules/Shortcuts.qml maps Hyprland global-shortcut/IPC-triggered actions into shell behavior.
Configuration and native QML API
The C++ plugin is the bridge between declarative QML and system/native capabilities. Its module root is plugin/src/Caelestia/CMakeLists.txt; domain APIs are exposed from submodules.
Configuration is typed and layered rather than read ad hoc by UI:
• plugin/src/Caelestia/Config/rootnodes.cpp
• plugin/src/Caelestia/Config/configattached.cpp
• plugin/src/Caelestia/Settings/settingsfile.cpp
It models defaults plus user files at ~/.config/caelestia/shell.json, token overrides, and monitor-specific overrides. QML should consume attached config/tokens APIs, preserving this boundary between persisted settings and rendering.
System-service integration
QML service facades orchestrate desktop integrations, while native services gather lower-level data:
• services/Hypr.qml, services/Audio.qml, services/Nmcli.qml
• plugin/src/Caelestia/Services/service.cpp
• plugin/src/Caelestia/Services/audioprovider.cpp
• plugin/src/Caelestia/Services/hyprdevices.cpp
Material dependencies include Hyprland, NetworkManager/nmcli, PipeWire, brightnessctl/DDC, lm_sensors, power-profiles-daemon, libcava, aubio, and libqalculate. Notifications, media players, wallpapers, weather, idle inhibition, recording, and display state are represented by QML services under services/.
Desktop surfaces and interactive modules
The main desktop-facing surfaces are independently wrapped modules:
• Background/wallpaper/visualizer: modules/background/Background.qml, modules/background/Wallpaper.qml
• Top bar and contextual popouts: modules/bar/BarWrapper.qml, modules/bar/popouts/Wrapper.qml
• Dashboard: modules/dashboard/Wrapper.qml, modules/dashboard/Content.qml
• Launcher: modules/launcher/Wrapper.qml, modules/launcher/services/Apps.qml
• Settings (“Nexus”): modules/nexus/Nexus.qml, modules/nexus/PageRegistry.qml
• Notifications/sidebar/OSD: modules/notifications/Wrapper.qml, modules/sidebar/Wrapper.qml, modules/osd/Wrapper.qml
Control flow is event-driven: shortcuts, compositor/system-service updates, and user actions mutate service/state objects; wrappers reactively show surfaces; content components bind to configuration and service models.
Security and session boundaries
Locking and session controls are isolated:
• modules/lock/Lock.qml
• modules/lock/Pam.qml
• modules/session/Wrapper.qml
PAM integration is supported by installed service definitions in assets/pam.d/fprint and assets/pam.d/howdy, enabling password, fingerprint, and Howdy authentication paths. Session actions invoke configured logout, poweroff, reboot, or hibernate commands; these are a privileged external-command boundary.
Data-heavy capabilities
Native models/providers avoid putting filesystem, image, sensor, and media processing in QML:
• App/file discovery: plugin/src/Caelestia/Models/appdb.cpp, plugin/src/Caelestia/Models/filesystemmodel.cpp
• Image cache/analysis: plugin/src/Caelestia/Images/imagecacher.cpp, plugin/src/Caelestia/Images/imageanalyser.cpp
• Metrics/audio/lyrics: plugin/src/Caelestia/Services/cpu.cpp, plugin/src/Caelestia/Services/lyrics.cpp, plugin/src/Caelestia/Services/cavaprovider.cpp
These feed launcher results, wallpaper/file dialogs, dashboard performance cards, media visualization, and lock/dashboard media displays without coupling those UIs directly to OS APIs.
Main entry points: shell.qml Shell root · CMakeLists.txt Caelestia plugin · BarWrapper.qml Desktop surfaces · appdb.cpp Native data models
Components 20
QML Shell
Quickshell composition and desktop surfaces.
- Shell root · Composes persistent services and feature modules.
shell.qml - Shell state · Cross-module state boundary.
services/ShellState.qml - Shared UI primitives · Per-screen state, window behavior, animation, and text styling.
components/ScreenState.qml - Shortcuts · Maps Hyprland-triggered actions into shell behavior.
modules/Shortcuts.qml - QML service facades · Reactive desktop-integration facades for Hyprland, audio, and network.
services/Hypr.qml - Desktop surfaces · Background, bar/popouts, dashboard, notifications, sidebar, and OSD.
modules/bar/BarWrapper.qml - Launcher · Shows application discovery results.
modules/launcher/Wrapper.qml - Nexus settings · Settings UI driven by a page registry.
modules/nexus/Nexus.qml - Lock screen · Isolated authentication surface.
modules/lock/Lock.qml - Session controls · Issues configured logout and power commands.
modules/session/Wrapper.qml
Native QML Plugin
C++ APIs, models, and system providers.
- Caelestia plugin · Declarative bridge to native capabilities.
plugin/src/Caelestia/CMakeLists.txt - Typed configuration · Layers defaults, user settings, tokens, and monitor overrides.
plugin/src/Caelestia/Config/rootnodes.cpp - Native system services · Provides low-level audio, Hyprland, and desktop data.
plugin/src/Caelestia/Services/service.cpp - Native data models · Handles app/files, images, metrics, lyrics, and visualization data.
plugin/src/Caelestia/Models/appdb.cpp
System Boundaries
Compositor, desktop services, and privileged session controls.
- User settings files · shell.json plus token and monitor-specific overrides.
- Hyprland compositor · Supplies IPC, global shortcuts, and display context.
- Desktop service stack · Network, PipeWire, sensors, brightness, media, and related system tools.
- PAM authentication · Supports password, fingerprint, and Howdy paths.
assets/pam.d/fprint - Session commands · Logout, poweroff, reboot, and hibernate commands.
Other components
- Build & packaging · Builds the plugin and installs the shell configuration.
CMakeLists.txt
Connections 26
- Build & packaging → Caelestia plugin: builds
- Build & packaging → Shell root: installs
- Shell root → Shell state: loads
- Shell root → Shared UI primitives: uses
- Shell root → Shortcuts: loads
- Shell root → QML service facades: loads
- Shell root → Desktop surfaces: composes
- Shell root → Launcher: composes
- Shell root → Nexus settings: composes
- Shell root → Lock screen: composes
- Shell root → Session controls: composes
- Shortcuts → Shell state: mutates
- Hyprland compositor → Shortcuts: triggers
- Hyprland compositor → QML service facades: IPC updates
- QML service facades → Caelestia plugin: uses native API
- Caelestia plugin → Typed configuration: exposes
- Caelestia plugin → Native system services: exposes
- Caelestia plugin → Native data models: exposes
- User settings files → Typed configuration: layers into
- Desktop service stack → Native system services: system data
- Typed configuration → Desktop surfaces: tokens and settings
- Native system services → Desktop surfaces: reactive models
- Native data models → Launcher: app results
- Native data models → Desktop surfaces: media and metrics
- Lock screen → PAM authentication: authenticates via
- Session controls → Session commands: invokes