Clavis Shell

Note

Clavis is under active development.

A desktop shell for niri, built with Quickshell, QML, Qt 6 and native C++ modules.

Highlights

• Keystone and edge bars
• Quick settings and sidebars
• Spotlight-style app, wallpaper, clipboard and web search
• Wallpaper transitions and niri-aware parallax
• Weather, weather maps and animated conditions
• MPRIS media controls and synchronized lyrics
• Screen and audio recording controls
• Dynamic Material theming with Matugen
• Settings center for shell, cursor, wallpaper, default apps and integrations
• Native QML modules for niri, media, weather, Cava, keyboard state and Material shapes

Project family

Clavis is split into three repositories:

Project	Role
Clavis Shell	Quickshell UI, reactive services and native QML modules
key-cli	key command, shell IPC/lifecycle, recording and clipboard integration
keytop	Standalone system monitor, TUI and machine-readable metrics

Install key-cli and keytop for the full Clavis experience.

Requirements

Core development dependencies include:

• Quickshell
• Qt 6
• CMake
• Ninja
• QtKeychain
• PipeWire
• libcava

Some features also use external tools such as Matugen, awww, cliphist, wl-clipboard, gpu-screen-recorder, FFmpeg and wlogout.

Development

Configure and build the native QML modules:

cmake -S . -B build \
  -G Ninja \
  -DCMAKE_BUILD_TYPE=Debug

cmake --build build

Run the source shell with the build-tree QML modules:

QML_IMPORT_PATH="$PWD/build/qml${QML_IMPORT_PATH:+:$QML_IMPORT_PATH}" \
  key shell

QML changes can be reloaded directly. Rebuild after changing native C++ modules.

The native QML modules are written to build/qml/ by CMake. qs.* imports are Quickshell root-relative modules; Clavis.* imports are native modules generated by qt_add_qml_module().

System install

cmake -S . -B build \
  -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/

cmake --build build
sudo cmake --install build

Start Clavis with:

key shell

Configuration

Most options are available from the Clavis settings center.

User configuration and state follow XDG paths, with the main shell configuration stored under:

~/.config/clavis/

Clavis-managed niri fragments are written under:

~/.config/niri/clavis/

Dynamic theming

Clavis uses Matugen to generate Material color schemes from the current wallpaper or a source color.

The settings center can generate themes for supported applications including btop, Cava, Kitty, Fcitx5, keytop, niri and Yazi.

Development checks

scripts/dev/format-qml.sh --check
scripts/dev/lint-qml.sh
scripts/dev/check.sh

lint-qml.sh refreshes the ignored .qmlls.ini tooling data when needed and uses the Quickshell VFS buildDir plus its importPaths. The quality gate also checks C++ format, shell syntax/lint, Python syntax, compiler warnings, the native build and CTest. Install the Qt/Quickshell tooling and clang-format/shellcheck in the development environment before running the complete gate. format-qml.sh --check keeps the normal check limited to changed QML files so legacy QML is not mass-rewritten; use format-qml.sh --all only for an explicit whole-tree formatter migration.

Acknowledgements

Clavis takes inspiration from and integrates ideas or components from projects including:

• end-4/dots-hyprland
• DankMaterialShell
• Caelestia Shell
• qml-niri
• Breezy Weather
• m3shapes
• HyDE

Third-party license notices are kept in licenses/.

License

See LICENSE.