Caelestia-demo.mp4
Note
This repo is the KDE Plasma port of caelestia-dots/shell.
Upstream runs on Hyprland; the port runs the same shell on KWin and Plasma. For the original
Hyprland dotfiles, see caelestia-dots/caelestia.
Requirements: Arch-based, Fedora, or Debian/Ubuntu - KDE Plasma 6 on Wayland, Qt 6.9+
curl -fsSL https://raw.githubusercontent.com/ladybug-me/caelestia-kde/main/install.sh | sh- Installer TUI: run the installer and choose Update
- GUI: Nexus -> Updates -> select branch -> Install Updates
- CLI:
bash update.shand choosemain(stable) ordev(bleeding edge)
Shell settings are preserved across updates.
Choose Uninstall from the installer TUI, or run:
bash ./uninstall.sh| Shortcut | Action |
|---|---|
Super |
App launcher |
Super + / |
Keybind cheatsheet |
Super + Enter |
Terminal |
Super + Tab |
Overview |
Super + 1-5 |
Switch workspace |
Super + B |
Notification sidebar |
Super + V |
Clipboard history |
Super + Shift + S |
Screenshot |
Super + Shift + A |
Google Lens |
Super + Shift + D |
Text recognition |
Super + Ctrl + S |
Screen recorder |
Super + Shift + C |
Color picker |
Super + Shift + V |
Emoji selector |
Open Nexus (Super, then >Settings).
- Appearance: wallpaper, colors, fonts, and the wallpaper slideshow
- Panels: every bar element, dashboard, launcher, sidebar and overview
- Desktop: window rules, the context menu, Krohnkite
- Shortcuts: rebind any built-in shortcut, or add a command shortcut
- Plugins: browse the store, or install a plugin you built yourself
Set the wallpaper from Appearance. The stock KDE wallpaper manager does not drive the color scheme, so using it leaves the shell on stale colors.
Settings are written to ~/.config/caelestia/shell.json.
| Problem | Fix |
|---|---|
| Widgets not appearing | Log out and back in, or run caelestia shell -d |
| Colors not applying | Run caelestia scheme set -n dynamic, or caelestia wallpaper -f <image>. See TROUBLESHOOTING.md |
| Install failed mid-way | Re-run bash ./scripts/setup.sh |
| Full reset needed | See TROUBLESHOOTING.md |
For detailed logs, enable Debug Mode in Nexus -> About -> Advanced, then run
caelestia shell -l. Bug reports and questions go to
GitHub Issues.
installer/ TUI installer and the per-distro package lists
tui/ C++ TUI source and its CMakeLists
data/ menu.json, theme.json, tui.version
distro/ per-distro package installation (arch, debian, fedora)
scripts/ install/update pipeline: the numbered steps and their shared lib/
src/ files copied onto the system, plus the vendored submodules
shell/ the QML shell and its C++ QML plugin
docs/ guides, plus design notes under docs/architecture/
tests/ bash tests for the step-script helpers
tools/ repo maintenance scripts, never shipped
assets/ the logo and screenshots used by the docs
.github/ workflows, issue and PR templates, CI checks
- caelestia-dots/shell and the Caelestia dotfiles by @soramanew - the design language, shell and dotfiles this port is built on
- ladybug-me - KDE port lead
- 0xSolanaceae - Head maintainer
- Bali10050 - Darkly Qt
- wrymt - Darkly GTK
- Haidir - icon set
- dim-ghub - v2.0.0 features
- dharmx - default wallpapers
GPL-3.0-or-later - see LICENSE.