caelestia-kde

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.

Installation

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

Updating

Installer TUI: run the installer and choose Update
GUI: Nexus -> Updates -> select branch -> Install Updates
CLI: bash update.sh and choose main (stable) or dev (bleeding edge)

Shell settings are preserved across updates.

Uninstalling

Open Settings, go to the About page, and choose Uninstall Caelestia. That opens the uninstaller in a terminal, where it asks for confirmation of its own.

You can also choose Uninstall from the installer TUI, or run the script from the checkout directly:

bash ./uninstall.sh

A packaged install has no script to run: the row names the package manager's command instead.

Keybinds

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

Configuring

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.

Troubleshooting

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.

Repository layout

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

Credits

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

License

GPL-3.0-or-later - see LICENSE.

ladybug-me/caelestia-kde

Projektdokument