Quickshell and Caelestia components, services and local changes

Quickshell runs desktop components written in QML. Caelestia and illogical-impulse are complete shells with separate configuration conventions. Selecting one does not make the other's paths or colors.json valid.

The current example uses Caelestia Shell v2.4.0. Start with a small independent component before navigating the full shell.

An independent clock

With Quickshell, QtQuick and a compatible Wayland compositor installed, save ~/.config/quickshell/doc-clock/shell.qml:

import Quickshell
import QtQuick

PanelWindow {
    anchors {
        top: true
        left: true
    }
    implicitWidth: 240
    implicitHeight: 48
    exclusiveZone: 0
    color: "#1e2530"

    SystemClock {
        id: clock
        precision: SystemClock.Seconds
    }

    Text {
        anchors.centerIn: parent
        text: Qt.formatDateTime(clock.date, "hh:mm:ss")
        color: "#f1f4f8"
        font.pixelSize: 22
    }
}

Launch from a graphical-session terminal:

qs -c doc-clock

The clock occupies the upper-left area. exclusiveZone: 0 reserves no tiled space, so choose a test location that does not obstruct controls. Stop it with Ctrl+C in its launching terminal. Quickshell introduction

When clock.date changes, its bound text reevaluates. The component does not manually poll the text widget.

From a clock to system services

Full shells expose audio, network and media state through service objects. Modules render the state and send user actions back through service methods.

Do not guess an audio property such as defaultSink.volume. Raw Quickshell and shell-specific wrappers can differ, and no default device may exist yet. Inspect the actual service type and installed API.

Three Caelestia configuration layers

1. ~/.config/caelestia/shell.json: user settings for appearance, applications, idle policy and screens.
2. Installed quickshell/caelestia/: modules, services, resources and compiled plugins.
3. Upstream source and local patches: implementation changes with a recorded base version.

Prefer public settings before editing source. Package-managed files may be overwritten during updates; follow upstream installation/customisation guidance.

Local adaptations include shell output restrictions, portrait locking layout and wallpaper sizing. They solve this desktop's constraints, not universal Caelestia requirements.

Startup and logs

qs -c caelestia -n starts the installed configuration and avoids a duplicate instance. Do not launch it separately when a user service already owns it.

The example service is named caelestia-shell.service:

systemctl --user status caelestia-shell.service
journalctl --user -u caelestia-shell.service -b -n 80 --no-pager

Other installations may differ. QML import errors suggest runtime or compiled-plugin paths; unknown properties suggest version mismatch; working processes with failed control commands require checking IPC instance selection.

Preserve the origin of local changes

Before updating, record upstream version, commit, local diff and user configuration. Afterwards verify startup, bar, notifications, locking and screen selection before theme hooks.

The current shell invokes an additional Matugen application-theme script; it does not use the earlier ii colors.json path. See theme distribution and session lifetime diagnosis.