Architecture and configuration

Programs and files

In the repository, user files live under home/. The installer links or copies them into the corresponding locations in your home directory.

How the shell is organised

shell.qml is the entry point. TopShell.qml owns the top surface: its shape, bar contents, fullscreen behaviour and input mask. NotchContent.qml draws the active face.

ShellState.qml owns shared state and the notch state machine. It gathers the clock, media, audio, battery, network and other data without being the interface itself.

The input mask limits pointer events to the visible shapes. Empty space between the bar icons lets clicks reach the desktop underneath.

Shared design, separate preferences

Colors.qml supplies the wallpaper palette and semantic colours. Appearance.qml supplies sizing, typography and motion tokens shared by the components.

Config.qml persists preferences in ~/.config/quickshell-rice.json. This keeps the user’s choices separate from the interface’s source files.

Talk to the shell

Quickshell exposes an IPC target named notch. These are useful when building a script or checking whether the shell is answering:

qs ipc call notch control
qs ipc call notch launcher
qs ipc call notch settings
qs ipc call notch overview
qs ipc call notch style
qs ipc call notch close

Each line is a separate command. control, launcher, settings and overview toggle their corresponding interfaces. style switches notch/island; close closes the current panel.

The service owns the process

Quickshell is supervised by a user service. To restart it:

systemctl --user restart quickshell

Starting a second shell manually can leave two instances competing for the same resources. Use the service when maintaining your normal desktop.

Go deeper

The shell’s technical notes are in README.en.md and README.md. They cover implementation decisions and measurements, including some older approaches. Check the current Lua and QML source when a note refers to a previous configuration format.