Mantle Shell

Lua desktop shell for Wayland built on the Mantle engine, with Arch Linux dotfiles for Hyprland and Niri.

Preview

20260913_181858_compressed.mp4

The shell

• mantle/ holds the shell config. The upstream engine provides the mantle binary, Lua API, and capabilities.
• Hyprland and Niri launch it at login and bind shortcuts to mantle toggle and mantle call.
• Saving any .lua file under ~/.config/mantle reloads the shell in place. An invalid edit keeps the active scene running and surfaces the error in the bar.

Area	Includes
Bar	Workspaces, Hyprland scratchpads, active window, keyboard layout, tray, clock, weather, system info, privacy, battery, volume, network, Bluetooth, updates, recording
Panels	Audio mixer, network, Bluetooth, media, calendar, notification history, pacman and dev-tool updates, recording, power
Launcher	Fuzzy app search, arithmetic, currency conversion
Overlays	Notifications, OSD, polkit agent, Bluetooth pairing, lock screen
Idle	Displays off, lock, suspend, with a settings modal. Replaces Hyprlock, Hypridle, Swaylock, and Swayidle
Wallpaper	Per output, shader transitions (disc, pixelate, portal, stripes, wipe), picker, Niri overview backdrop
Power	Charger OSD, low-battery notifications, automatic suspend

Requirements

For	Needs
Shell	Mantle engine binary
Compositor	Hyprland 0.56+ (Lua config) or Niri
Deployment	Arch Linux, Git, GNU Stow
Fonts	CaskaydiaCove Nerd Font Propo, Noto Sans, Noto Sans CJK JP, Noto Color Emoji
Shell helpers	curl, libnotify, wl-clipboard, xdg-utils, gpu-screen-recorder, slurp
Screenshots	hdrshot using hyprshot, satty, wl-copy, flock

Installation

Warning

Back up existing dotfiles first; GNU Stow will not overwrite conflicting files. Review Configuration for hardware and user-specific paths.

1. Install the engine. Required before launching the shell.

2. Stow core packages.

git clone https://github.com/anasgets111/dotfiles.git
cd dotfiles
stow -t "$HOME" mantle hypr niri home config xdg-desktop-portal bin

3. Stow optional packages.

stow -t "$HOME" fish nvim kitty mpv                     # shell, editor, terminal, player
stow -t "$HOME" ghostty alacritty foot wezterm nushell   # alternative terminals and shells

Unstow packages with stow -D -t "$HOME" <package>. The home package provides ~/.stowrc pointing at this repository, allowing stow and stow -D to run from any directory without -t. arch-install.sh automates the full Arch install and stow setup for my machines.

Keybinds

Core shortcuts. Full mappings live in keybinds.lua for Hyprland and the binds block of config.kdl for Niri.

Keys	Action
Super+Space	Launcher
Super+Shift+W	Wallpaper picker
Super+Ctrl+P	Idle settings
Super+L	Lock (loginctl lock-session)
Print / Ctrl+Print	Screenshot region / output
Shift+Print	Start or stop recording
Super+M	Mute microphone

Configuration

What	Where
Monitors, including an ICC profile	monitors.lua, or outputs in config.kdl
Startup apps	startup.lua, or spawn-at-startup in config.kdl. Niri requires an absolute path to mantle
Wallpaper folder	wallpaper.FOLDER in lib/wallpaper.lua
Colours, sizes, fonts	config/theme.lua, fonts table in shell.lua
Update-panel tools	config/dev_tools.lua
Editor stubs	workspace.library in .luarc.json, pointing at the engine's lua-meta
Weather location	Derived from system timezone
Runtime state	~/.local/state/mantle/state.json

Repository layout

Path	Contents
mantle/	components/, config/, lib/, modules/, and transition shaders/
hypr/, niri/	Compositor configurations for Hyprland and Niri
home/, config/	Shell profile, .stowrc, XDG, Starship, Fastfetch, app flags
fish/, nushell/, nvim/	Shells and editor
kitty/, ghostty/, alacritty/, foot/, wezterm/	Terminals
mpv/	mpv config and scripts
bin/	Install, backup, and screenshot scripts
NixConfig/	Inactive NixOS flake for an NVIDIA/Hyprland and an Intel/Niri machine

Credits

Inspiration and reference shells:

• DankMaterialShell
• Noctalia
• caelestia
• HyprlandDE