Caelestia Island Suite

Caelestia Island Suite is an integrated Caelestia Shell overlay for Hyprland. It combines the Dynamic Island, Bottom Notch, enhanced settings, and a native Task Manager in one repository.

Caelestia Dynamic Island with detached recording and timer Live Activities on workspace 4

×

One Caelestia process, four integrated tools, and no edits to the packaged shell.

Included features

• Top Dynamic Island: multi-monitor notch and floating modes, seven swipeable routes, media controls and seek equalizer, compact exclusive notifications, OSD, battery events, workspaces, wallpapers, launcher, Control Center, and a native settings app. Detached Live Activities cover timers, stopwatch, GNOME Clocks, recordings, connectivity, privacy, and system toggles.
• Bottom Notch Dock: an auto-hiding active-workspace task dock with exact window activation, stale-safe delayed previews, an exact-window action menu, a right-side Alt+Tab Activity View, Launcher gesture compatibility, and its own settings app.
• Enhanced Caelestia Settings: a project-owned Nexus overlay with settings search and deep links, Colours, semantic Material icon providers, weather location, update checks, HyprPM management, and links to both notch settings apps.
• Native Task Manager: grouped applications and processes, search, sorting, CPU and memory accounting, performance history, details, adaptive collection, exact-window activation, and guarded end-task actions.
• Documentation and tests: implementation plans, decisions, configuration references, evaluation notes, static checks, live Island smoke tests, and a deterministic Task Manager helper suite.

FEATURE.md is the source of truth for behavior that currently exists in code. Planning documents may describe future work and should not be read as proof that every proposal is implemented. The Task Manager core is implemented and test-covered; its longer soak, complete accessibility, and multi-monitor release audits remain tracked work.

Showcase

Every image below was captured from the implemented overlay on Hyprland workspace 4.

Top Dynamic Island

Ongoing work stays visible in detached bubbles without expanding the main Island. Persistent activities expose real controls, while repeated system changes replay one bounded pop animation instead of creating duplicates.

Compact Island-only notification on workspace 4

×

One compact presenter replaces the duplicate legacy popup while preserving notification history.

←1 / 2→

Bottom Notch and Task Manager

The dock and Activity View share exact Hyprland window addresses. Alt+Tab opens the right-side switcher, Alt+Shift+Tab cycles backward, and click or Enter focuses the selected exact window. The Task Manager complements that view with grouped process accounting and on-demand performance collection.

Bottom Notch Activity View beside the Task Manager on workspace 4

×

A bounded, keyboard-accessible switcher for the active workspace.

←1 / 2→

Enhanced Settings

Enhanced Caelestia Nexus Plugins page showing live HyprPM inventory on workspace 4

×

The Plugins page separates Caelestia runtime extensions from HyprPM compositor plugins.

Inventory is read-only on open. Mutations require a reviewed confirmation and remain visible in HyprPM's interactive terminal.

Compatibility

The overlay was built against:

• Caelestia Shell 2.3.0, revision 94d5eb9e6fe9c6b1f69e663d9ed410a441e2d67f
• Caelestia CLI 1.1.2
• Quickshell 0.3.x, verified with 0.3.1
• Hyprland 0.56.2
• Python 3.14.x for Task Manager helpers, verified with 3.14.7

Caelestia Shell must already be installed at /etc/xdg/quickshell/caelestia. The overlay reuses upstream assets, services, components, and most modules through symlinks. It never edits the packaged source. UPSTREAM.md documents the ownership and rebase model.

Installation

Clone and install the repository with:

git clone https://github.com/yotadaa/caelestia-island-suite.git
cd caelestia-island-suite
./install.sh --link

The installer links caelestia/ to ~/.config/quickshell/caelestia, installs four desktop entries and the suite icon, and preserves existing files under ~/.config/caelestia/. A different Quickshell caelestia configuration is moved to a timestamped backup under:

~/.local/state/caelestia-island-suite/backups/

Before writing files, the installer runs quickshell --version and Quickshell's Qt private-ABI compatibility check. It repeats the compatibility check before --restart stops a live shell. Restart captures matching processes, waits for the old PID to exit, then verifies that the replacement instance started.

Restart the shell after reviewing the installer output:

./install.sh --link --restart

Useful alternatives:

./install.sh --dry-run       # show every planned filesystem change
./install.sh --copy          # install a snapshot instead of a repository link
./install.sh --no-desktop    # skip desktop entries and the application icon

Link mode is recommended for a Git checkout because pulling a new commit updates the installed overlay in place. User configuration remains separate in ~/.config/caelestia/.

Opening the settings

After the shell is running, use these application launcher entries:

• Caelestia Settings
• Caelestia Island Settings
• Caelestia Bottom Notch Settings
• Caelestia Task Manager

Equivalent IPC commands are:

quickshell -c caelestia ipc call settings openPage wallpaper-style -1
quickshell -c caelestia ipc call island settings
quickshell -c caelestia ipc call bottomDock settings
quickshell -c caelestia ipc call taskManager open processes

Validation

Run the non-destructive repository checks with:

tests/install_static.sh
tests/settings_static.sh
tests/notch_gesture_static.sh
tests/notch_live_activities_static.sh
tests/notch_singleton.sh
tests/task-manager/smoke-task-manager.sh
python tests/task-manager/benchmark_collector.py

With the custom shell already running, the live Island test is:

tests/notch_smoke.sh

Repository layout

Updating or recovering

Before rebasing onto a new Caelestia release, run:

tools/settings/audit-overlay.sh

If an upstream update breaks the owned Nexus overlay, follow the recovery procedure in UPSTREAM.md. Restore an installer backup by moving the desired backup to ~/.config/quickshell/caelestia while the shell is stopped.

On Arch Linux, a Qt upgrade can require rebuilding the AUR quickshell-git package because Quickshell uses Qt private APIs. If the installer reports an ABI failure, rebuild it and start Caelestia again:

paru -S --rebuild quickshell-git
caelestia shell -k
caelestia shell -d

Use yay -S --rebuild quickshell-git when using Yay. caelestia shell reload is not a reload shortcut in Caelestia CLI 1.1.2; use the explicit stop and start commands above.