Skip to content

Creating mi-shell

Overview

mi-shell is a comprehensive, highly integrated, vertical desktop shell and utilities suite built specifically for the Niri scrollable-tiling window manager.

Operating on a Zero-Footprint philosophy, it eliminates the need for heavy, monolithic desktop environments by leveraging standard Linux system layers, core CLI utilities, and deep Wayland protocol integration.

It provides a centralized interface for window handling, real-time telemetry, notification routing, media manipulation, hardware locks, network/VPN configuration, and local storage mounting.

Module Component Architectural Implementation & Behavior
The Vertical Bar Houses the clock, Niri workspace tracking, system tray (nm-applet), volume, brightness, pinned adaptive apps (dimmed when idle, illuminated when focused), and running tasks.
Control Centre Centralized overlay providing instant management of network attachments, VPN routing, Bluetooth states, hot-reloaded themes, wallpaper grids, and session menus.
Theme & Wallpaper Engine Controls 206 individual themes split across 6 distinct families. Features a grid-based asset picker (swaybg) and provides synchronized hot-reloading to instantly change the style of the shell, kitty terminal, and browser without process restarts.
System Info & Telemetry A lazy-loaded modal exposing host metrics—including CPU distribution load, localized core thermals, kernel information, and filesystem/disk consumption.
Productivity & Agenda Renders an interactive calendar grid utilizing cal, with a deep backend bridge fetching a 7-day personal agenda layout directly from khal (supporting remote vdirsyncer hooks).
Caffeine Mode (Sleep Inhibition) Displays an interactive status cup driven by an underlying watcher script (mi-caffeine). Inhibits system/display idle loops during crucial runtime processes (such as rclone operations) or when manually toggled.
Storage & USB Management Native block-device abstraction via udisks2, allowing the user to mount, safely unmount, and mechanically power off physical external drives directly from the bar interface.
Network & Secrets Bridge Direct management overlays for Wi-Fi configurations and VPN endpoints handled seamlessly via NetworkManager. Security credentials are offloaded cleanly to local Secret Service providers rather than sandboxed utilities.
Launcher & Notification Daemons Embeds a custom, high-speed text-filtering application launcher (rofi-style replacement) alongside a built-in, layout-aware notification subsystem (mako-style replacement).
On-Screen Display (OSD) Transient, auto-hiding feedback overlays capturing dynamic hardware level modifications for audio streams and panel backlights (brightnessctl).

Technical Stack & Dependencies

  • Framework: Quickshell (A native Wayland desktop shell scripting and layout engine).

  • Languages: Declarative QML (Qt Modeling Language) for frontend structural design, coupled with JavaScript for state mutation and UI logic.

  • Inter-Process Communication (IPC): Powered by Quickshell.Io for non-blocking, asynchronous shell processing, alongside direct Niri IPC commands (niri msg).

  • Secret Management: Integrated with local Secret Service protocols—optimized specifically to fetch keys securely from local KeePassXC instances, entirely avoiding traditional GNOME-Keyring or KWallet engines.

Deployment, Architecture & Lifecycle

The shell abstracts its deployment and configuration lifecycle into distinct layers to guarantee lightning-fast interface response times while preventing UI thread locking.

1. Configuration & Scoping

System Layer: Fallback system-wide baseline templates reside safely inside /etc/xdg/quickshell/mi-shell/.User Layer: The live user workspace runs strictly out of ~/.config/quickshell/mi-shell/, utilizing static local config profiles for customized pinned application layouts and preferences.

2. Environment Initialization (mi-shell-setup)

The historical reliance on unstructured init.sh workflows is replaced entirely by a dedicated setup tool: mi-shell-setup. * Verification: Executed post-installation to inspect, parse, or generate your Niri layout schema. * Bootstrapping: Sets up necessary workspace assets, validates wallpaper directories, and appends the shell's configuration tree directly into Niri's main controller file.

3. Niri Native Hooking (mi-shell.kdl)

Rather than spinning up untracked background processes via terminal environments, mi-shell cleanly integrates into Niri's runtime architecture via a dedicated sub-configuration module (include "mi-shell.kdl"):

spawn-at-startup "/usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1"
spawn-at-startup "mi-power"
spawn-at-startup "nm-applet"
spawn-at-startup "quickshell" "-c" "mi-shell"
spawn-at-startup "sh" "-c" "swaybg -i $(cat ~/.config/quickshell/mi-shell/wallpaper.conf) -m fill"
binds {
    Mod+D { spawn "qs" "-c" "mi-shell" "ipc" "call" "launcher" "toggle"; }
    Mod+S { spawn "mi-caffeine"; }
    Mod+Plus { consume-or-expel-window-left; }
    Mod+Dead_Grave { consume-or-expel-window-right; }
}

4. Native Arch Linux Packaging

To ensure absolute system compliance and cleanly handle dependencies (such as qt6-wayland, playerctl, mpv-mpris, and xwayland-satellite), mi-shell is compiled and rolled out through a native PKGBUILD.

The only caveat is quickshell-git is an AUR package and should either be installed manually, or with the help of an AUR helper. Guides for both Paru and Yay are in the documentation.

After deployment, executing mi-shell-setup ensures configuration directories are aligned and that Niri is instructed to hot-load the mi-shell.kdl subsystem.

The Git repository is mi-shell-git

Last updated: 08/06/2026

Posted

18:40 01-05-2026