dux-shell

Project Overview

When you want a complete desktop on Wayland, Dux Modular Shell offers one assembled answer: a single shell supplies the top bar, launcher, control center, notification center, lock screen and desktop widgets. The interface is rendered with Quickshell QML while system integration lives in the dms daemon written in Go, folding work that usually needs waybar, swaylock, swayidle, mako, fuzzel and polkit into one repository. It is a monorepo: quickshell/ holds the UI, core/ the Go backend and CLI, and distro/ the packaging files.

Item	Value
Platform	Wayland (niri, Hyprland, Sway and others)
Stack	Quickshell / Qt 6 QML + Go 1.27.3
Current version	v2.1.2
License	MIT

One shell replaces a whole row of separate components, and its themes and plugin set move with you.

Key Features

• Dynamic theming: pulls colors from the wallpaper through matugen and dank16, rewriting GTK, Qt, terminal and VS Code / VSCodium themes
• System monitoring: the dms daemon samples CPU, RAM, GPU load and temperatures, with a searchable process list
• Launcher: Spotlight-style search across apps, files, emoji, open windows, a calculator and commands
• Control center: network, Bluetooth, audio devices, display settings and night mode in one panel
• Notification center: groups by application with rich text and keyboard navigation
• Media and clipboard: MPRIS transport controls, calendar, weather and clipboard history with image previews
• Session management: lock screen and idle detection with separate AC and battery auto-lock and suspend rules
• Plugin system: ~/.config/dms/plugins.lock.json records managed plugins with exact Git commits so the same set can be reproduced elsewhere

Interface and Components

• TopBar: multi-monitor status bar with workspace switching
• DBar: customizable widget bar with plugin support
• Dock: application dock with window management
• DDash: dashboard aggregating metrics and quick toggles
• DIsland: dynamic-island style notification area at the top of the screen
• OSD and notifications: overlays for volume and brightness plus app notification popups
• Desktop layer: desktop widget layer, desktop context menu, blurred or video wallpaper layers

Command Line and IPC

• dms run: start the shell
• dms ipc call: invoke capabilities per object, such as dms ipc call spotlight toggle or dms ipc call audio setvolume 50
• dms brightness list: enumerate controllable displays
• dms plugins search / lock / restore: browse the registry, refresh the lockfile, restore from it
• dms doctor: verify the runtime environment

Target Audience

• Wayland users on niri or Hyprland
• Linux desktop users who want one consistent look
• People needing multi-monitor bars and workspace switching
• Developers writing desktop components in QML

Quick Start

1. Confirm you are in a Wayland session on niri, Hyprland, Sway, MangoWC, labwc, Scroll or Miracle WM
2. Install from your distribution: dux-shell on Arch, dux-shell-git from the AUR, with Fedora, Debian, Ubuntu, openSUSE and Gentoo packaging under distro/
3. Run dms run once and check that the bar and launcher appear
4. Pick a wallpaper in settings; colors and terminal or editor themes regenerate from it
5. Browse extensions with dms plugins search, then run dms plugins lock to pin versions
6. On NixOS, import homeModules.dank-material-shell from the flake

System Requirements

Item	Requirement
Session	Wayland; X11 is not supported
Compositor	Full support on niri, Hyprland, Sway, MangoWC, labwc, Scroll and Miracle WM
Runtime	Quickshell and Qt 6; Go 1.27.3 when building from source
Distributions	Arch, Fedora, Debian, Ubuntu, openSUSE, Gentoo, FreeBSD, NixOS
IPC	UI and the dms daemon negotiate an API version, currently requiring apiVersion >= 38

Notes

• Wayland only: workspaces, layer-shell surfaces and screenshots rely on Wayland protocols, so X11 has no path
• Compositor sets the ceiling: only the seven listed compositors get full workspace switching, overview and monitor management; others lose features
• Wide takeover: the bar, lock screen and idle management are handled here, so existing waybar and swaylock configs stop applying
• The lockfile pins versions: ~/.config/dms/plugins.lock.json fixes exact commits, so restored plugins do not follow upstream until dms plugins lock runs again