Project Nirav: A Modular QuickShell Overlay for the Niri Compositor

Prateek Yadav

Dept. of Computer Science
RPTU Kaiserslautern-Landau
Return to Main Paper

Abstract—The Linux ecosystem is increasingly moving towards Wayland-based compositors. Nirav presents a novel approach to desktop environment creation by overlaying a modular, QML-based shell onto the Niri infinite-scroll compositor. This paper details the system's architecture, including its Gruvbox-themed aesthetic, real-time system monitoring capabilities, and custom widget framework. Performance metrics indicate minimal resource overhead while maximizing user utility through integrated media controls and dynamic workspace management.

Index Terms—Wayland, Niri, QuickShell, Qt6/QML, Human-Computer Interaction, GPU Acceleration, System Monitoring.

I.Introduction

The transition from X11 to Wayland has necessitated new paradigms for system interaction. Standalone compositors like Niri offer robust window management but lack the integrated "shell" experience of GNOME or KDE. Nirav fills this niche by providing a lightweight, aesthetically consistent overlay built on the QuickShell framework.

The primary design philosophy of Nirav is "functional minimalism." It adheres to the specific Gruvbox Material Dark color scheme to reduce eye strain while providing high-density information through smooth animations and vector iconography.

II.System Architecture

Nirav is architected as a client-side application communicating with the compositor and system hardware layers.

A.The QuickShell Runtime

By leveraging QuickShell (based on Qt6 and QML), Nirav achieves hardware-accelerated rendering. This ensures that UI elements, such as the Cava audio visualizer, do not consume CPU cycles reserved for application logic.

B.Widget Framework

The shell is composed of independent "Widgets" that handle specific domains:

Workspace Widget: Visualizes Niri's infinite scroll layout using Nerdfont icons.
System Monitor: Reads /proc/stat and `lm_sensors` to display CPU load, RAM usage, and core temperatures with color-coded threshold alerts.
Connectivity Suite: Includes a WiFi widget (SSID on hover, `impala` TUI launch on click) and Bluetooth widget (`bluetui` integration).

III.Feature Analysis

A.Media Integration

Nirav implements the MPRIS protocol to display current track information (Artist - Title) and provide playback controls. Uniquely, it integrates a Cava visualizer directly into the bar, creating a dynamic audio spectrum that reacts to system audio output.

B.Power Management

The Battery widget features hover-expand details and a dedicated "Right-Click" action to spawn `battop` in a floating window, offering granular insight into discharge rates and battery health.

C.Visual Aesthetic

The entire UI is strictly typed to the Gruvbox Material Dark palette. Text rendering utilizes the JetBrainsMono Nerd Font for readability and code-ligature support.

                        [Niri Compositor Protocol]

                        |

                        v

                        [QuickShell Engine (Qt6)]

                        / | \

                        [Sys Mon] [Media/Cava] [Workspaces]

Fig. 1. Nirav Architecture Diagram

IV.Deployment

Installation requires `quickshell` and `niri`. The codebase includes comprehensive documentation on "Widgets & Theming", allowing users to fork and customize the QML definitions.

git clone https://github.com/kkYrusobad/Nirav

V.Future Work

Future iterations will focus on a plugin system for third-party widgets and tighter integration with Niri's IPC for window movement control directly from the shell.

Availability

The full source code, documentation, and release history are hosted on GitHub.

View Repository