quickshell

Quickshell components for a Hyprland desktop, each one self-contained in its own directory. They are separate shells, not modules of a single bar: any of them can run alone, and running one does not require the others. One of them, desktop/, is itself a host for modules, which its own README covers.

Visually they follow unified-desktop-theme: Catppuccin Macchiato as the fixed base, Noto Sans for UI text, and an accent that tracks the wallpaper. That accent is read from the file udt-accent already writes, so the two repos stay independent, this one has no build-time dependency on that one.

Implementations

desktop/          the drawer: sound, mail, VMs, appearance
appearance/       wallpaper picker and colour scheme switcher
window-switcher/  open windows as live previews in a grid, on ALT+TAB
keybinds/         live keybind reminder, on SUPER+k

Each directory has its own README covering what it does and how to run it.

Running one

qs -p ./desktop

To start one with the session, from Hyprland:

exec-once = qs -p ~/Programming/GIT/quickshell/desktop

Quickshell uses private Qt APIs, so it must be rebuilt after every Qt update. qs --version should report the same Qt as the installed one.

Some components ask the compositor for an effect they cannot draw themselves, such as the blur behind the sound module's OSD. Those rules live in the Hyprland config rather than here, and each component's README gives the block to add. They are optional: without the rule the component renders without that effect.

License

GPLv2 only. See LICENSE.

Development Approach

This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.

All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.

The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.