shell

caelestia-shell is a custom desktop shell for Linux users running Hyprland, a tiling window manager. A desktop shell is the visual layer that sits on top of your display and provides things like a status bar, notification popups, app launchers, a clock, a system tray, and other widgets you see around the edges of your screen. Most Linux setups use a tool called Waybar for this, but caelestia-shell replaces that entirely with its own implementation built on Quickshell, a Qt-based framework for building desktop widgets.

The shell is written in QML, the language used by Qt applications for describing visual interfaces. It is part of a larger collection of configuration files (called "dotfiles" in Linux customization circles) for the caelestia aesthetic setup. If you only want the shell component rather than the full configuration set, this repository is the right starting point.

Installation options include an AUR package for Arch Linux users, a Nix flake for NixOS and home-manager setups, and a manual build using CMake and Ninja. The manual route has a long list of dependencies covering things like a brightness controller, audio libraries, network management, temperature sensors, a music visualizer, a calculator library, and specific fonts. The shell is started by running a command from the terminal, and if the full caelestia dotfiles are installed, it launches automatically on login.

Once running, keybinds are managed through Hyprland's global shortcuts system. A command-line tool called caelestia-cli lets you control the shell from scripts or key combinations, with commands for toggling drawers, controlling media playback, locking the screen, switching wallpapers, and opening a color picker.

Wallpapers are read from a folder in your home directory, and a profile picture for the dashboard panel is read from a file called ~/.face. All configuration options live in a single JSON file.