README.md

May 28, 2026 · View on GitHub

blxshell

Material You Desktop Environment for Hyprland

https://github.com/user-attachments/assets/a82b691f-ba58-4d4f-b756-543f4b52b5cb

A fully custom Wayland desktop shell built with Quickshell and Hyprland.
Dynamic Material You color theming generated from your wallpaper using materialyoucolor.

Install

blxshell has moved to a CLI-based runtime layout. The installer now places the shell in ~/.local/blxshell and installs the blxshell command to ~/.local/bin/blxshell.

local install:

git clone https://github.com/binarylinuxx/dots
cd dots/
./install.sh

remote install:

curl -fsSL https://bshell.zapzig.org/get_remote | bash

Note

currently bad support for portable devices and wifi stuff because I'm as main maintainer using A PC and work still in progress anything will work properly expect battery module

for better integration of mediaplayer with browsers you would like to install this extensions(either stable working are not granted):

NixOS

import the flake and add packages:

# flake.nix
blxshell.url = "github:binarylinuxx/dots";

# configuration.nix
environment.systemPackages = with pkgs; [
  inputs.blxshell.packages.${pkgs.system}.blxshell
  inputs.blxshell.packages.${pkgs.system}.blxshell-custom-fonts
];

the Nix packages provide the shell runtime, CLI wrapper, and fonts — but you still need to copy the .config/quickshell directory from the dots repo to your $HOME:

git clone https://github.com/binarylinuxx/dots ~/dots
cp -r ~/dots/.config/quickshell ~/.config/quickshell

the packages act as the shell/wrapper layer on top of the Hyprland.

for all MPRIS/media player correct functionality, add the flake input and import the module:

# flake.nix inputs
blxshell.url = "github:binarylinuxx/dots";

# configuration.nix
imports = [ inputs.blxshell.nixosModules.default ];

services.blxshellMprisFixForZen.enable = true;

this single option(which you can actually do urself):

enables services.playerctld (required for media player tracking)
installs kdePackages.plasma-browser-integration (native host for browser metadata)
sets MOZ_APP_SYSTEM_DIRS so Firefox/Zen finds the native messaging manifest

restart the browser after rebuilding.

Shell Components

Component	Description
Bar	Top panel -- workspaces, system tray, clock, battery, audio, network
Launcher	App launcher with emoji, clipboard and wallpaper modes
Lockscreen	Material You bold lockscreen with PAM authentication
Power Menu	Shutdown, reboot, suspend, logout, lock
Notifications	Built-in notification daemon
Background	Wallpaper with parallax effect and startup zoom animation
Settings	GUI settings panel (`Win+S`)
Audio OSD	Volume and brightness overlay

Design

Material You color scheme generated from wallpaper via col_gen (Python)
Material Symbols Rounded icons throughout the entire shell
All colors are reactive -- change wallpaper, the entire shell updates
Smooth animations and transitions on every interaction
Fully configurable via config.json

Stack

Component	Tool
Compositor	Hyprland
Shell / Bar / Widgets	Quickshell (QML)
Color generation	col_gen (materialyoucolor)
Terminal	Ghostty
Shell	Fish
Prompt	Starship
Fetch	Fastfetch

IPC Control

Use the blxshell CLI for normal control. It wraps the correct Quickshell path and runtime environment.

blxshell start
blxshell reload
blxshell restart
blxshell log
blxshell theme /path/to/wallpaper.png
blxshell lock
blxshell powermenu

The shell still exposes lower-level IPC handlers through qs ipc when you need direct debugging.

qs ipc call lockscreen lock
qs ipc call -- powermenu toggle

Hyprland keybind examples:

bind = SUPER, L, exec, blxshell lock
bind = SUPER, Escape, exec, blxshell powermenu

Keybinds You Must Know

Keybind	Action
`Super + Return`	Open terminal
`Super + Space`	Open launcher
`Super + I`	Switch workspace
`Super + S`	Open settings
`Super + L`	Lock screen
`Super + P`	Power menu

Project Structure

.config/quickshell/
  shell.qml                 # Main entry -- all components, IPC, colors
  config.json               # User settings (editable via Settings panel)
  Colors.json               # col_gen generated Material You colors
  col_gen/                   # Python color generator (uv project)

  bar/
    Bar.qml                 # Top bar layout
    widgets/                # Clock, Audio, Battery, Network, Workspaces, etc.

  modules/
    Background.qml          # Wallpaper + parallax + fallback gradient
    BackgroundClock.qml     # Desktop clock overlay
    LockContext.qml          # PAM authentication logic
    LockSurface.qml          # Lockscreen UI
    PowerMenu.qml            # Power/logout menu

  launcher/                 # App launcher
  notifications/            # Notification daemon
  widgets/                  # Settings, Audio OSD, Screen corners
  services/                 # NetworkManager, Sway, OS detection
  lockscreen/pam/           # PAM config for lockscreen auth

Installation

Arch-based systems and openSUSE Tumbleweed are handled by the install script. Unsupported systems can still install the dotfiles, but package setup is skipped.

# One-liner (remote)
bash <(curl -fsSL https://raw.githubusercontent.com/binarylinuxx/dots/main/install.sh)

# Or clone and run locally
git clone https://github.com/binarylinuxx/dots.git
cd dots
./install.sh

The installer will:

Install yay if not present
Build/install Arch metapackages or install openSUSE packages from the blxshell OBS repo
Install the blxshell runtime to ~/.local/blxshell
Install the blxshell CLI to ~/.local/bin/blxshell
Optionally backup and replace ~/.config

Configuration

All settings live in ~/.config/quickshell/config.json and can be changed from the Settings panel (Win+S).

{
    "barFloating": false,
    "barOnTop": true,
    "barHeight": 35,
    "barRadius": 30,
    "screenCorners": true,
    "workspaceCount": 10,
    "workspaceStyle": "dots",
    "wallpaperParallax": true,
    "wallpaperStartupZoom": true,
    "fontFamily": "Rubik",
    "fontSize": 14
}

my friend's dots JES