z-bar-qt/README.md

ZShell

A feature-rich desktop shell for Hyprland built with Quickshell and Qt6/QML. Provides a modern, Material Design 3 inspired status bar, application launcher, notification center, wallpaper manager with dynamic color theming, and lock screen.

Features

• Status Bar - Configurable top panel with workspace indicators, audio controls, system resource monitors (CPU/RAM/GPU), system tray, clock with calendar, and notification bell
• Application Launcher - Fuzzy search with app frequency tracking, special search prefixes for filtering by category, description, keywords, etc.
• Notification Center - Full notification daemon with grouped notifications, popups, persistent storage, and Do Not Disturb mode
• Wallpaper Manager - Browse and select wallpapers with live preview carousel
• Dynamic Color Theming - Automatic Material Design 3 color palette generation from wallpapers
• Lock Screen - Secure session lock with PAM authentication
• Hyprland Integration - Deep integration with Hyprland for workspaces, window focus, keyboard state, and more

Dependencies

• Qt 6.9+
• Quickshell
• Hyprland
• Python 3 with materialyoucolor and Pillow (for dynamic color generation)
• PipeWire (for audio)
• Aubio
• DDCUtil
• Mpris

Installation

Arch Linux

For arch-based distros, there is a pkgbuild available at

cmake -B build -G Ninja
ninja -C build
sudo ninja -C build install

This installs the QML plugin to /usr/lib/qt6/qml.

NixOS

Note that not all features work well. This is due to limited testing on NixOS.

In your flake.nix file, add the following in your inputs.

inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    z-bar-qt = {
        url = "github:Zacharias-Brohn/z-bar-qt/";
        inputs.nixpkgs.follows = "nixpkgs";
    };
};

Below a full example of what it could look like.

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    z-bar-qt = {
        url = "github:Zacharias-Brohn/z-bar-qt/";
        inputs.nixpkgs.follows = "nixpgks";
    };
  };

  outputs =
    inputs@{
      nixpkgs,
      self,
      ...
    }:
    let
      system = "x86_64-linux";
      pkgs = import nixpkgs { inherit system; };
    in
    {
      nixosConfigurations.nixos = nixpkgs.lib.nixosSystem {
        specialArgs = {
          inherit inputs;
          inherit system;
        };
        modules = [
          ./configuration.nix
        ];
      };
    };
}

Now you can add z-bar-qt as a nixpkg in environment.systemPackages (or optionally in your homePackages). It is named zshell and for cli options; zshell-cli.

{ pkgs, inputs, ... }:

{
    environment.systemPackages = with pkgs; [
    inputs.z-bar-qt.packages.${system}.zshell
    inputs.z-bar-qt.packages.${system}.zshell-cli
    ];
}

You can now run zshell to run the bar. zshell-cli can be used for additional options.

Configuration

Configuration is stored in ~/.config/zshell/config.json. Options include:

Option	Description
appCount	Max apps shown in launcher
wallpaperPath	Directory containing wallpapers
baseBgColor / baseBorderColor	Fallback colors when dynamic colors disabled
accentColor	Custom accent color override
useDynamicColors	Enable Material Design 3 theming from wallpaper
barConfig	Enable/disable widgets and configure popouts
transparency	UI transparency levels
baseFont	System font
animScale	Animation speed multiplier
gpuType	GPU type for resource monitoring (amd, nvidia, intel)

Launcher Search Prefixes

Prefix	Filter
>i	App ID
>c	Categories
>d	Description/comment
>e	Exec command
>w	WM class
>g	Generic name
>k	Keywords
>t	Terminal apps only
>wallpaper	Wallpaper picker

Project Structure

├── shell.qml          # Main entry point
├── Bar.qml            # Status bar
├── Wallpaper.qml      # Wallpaper display layer
├── Components/        # Reusable UI components
├── Config/            # Configuration singletons
├── Modules/           # Main functional modules (Launcher, NotificationCenter, etc.)
├── Daemons/           # Background services (notifications, audio)
├── Helpers/           # Utility singletons
├── Plugins/ZShell/    # Native C++ plugins
└── scripts/           # Helper scripts (color generation, fuzzy search)

Inspiration and Acknowledgements

This project was inspired by the following repositories and resources, which helped me learn both Quickshell and QML:

• Caelestia
• end-4 dots-hyprland

Thank you to the maintainers and contributors of these projects for sharing their work.

License

See repository for license information.