Moonrice

A full desktop ecosystem for Hyprland + moonshell (caelestia fork) + TUI power suite on Arch / CachyOS. Distro-grade installer: from a clean Linux install it sets up packages, configs, the moonshell desktop shell, wallpaper engine, theming and the whole TUI stack — all keyboard-first.

---

The Ecosystem

Moonrice is structured like the great dotfile ecosystems (end-4/dots-hyprland, caelestia-dots): a shell for the desktop UI, a Lua-based Hyprland config, a theming engine, a wallpaper engine, and an installer/CLI tying it all together.

moonrice/
├── install.sh              distro-grade installer (packages + configs + shell)
├── packages.txt            full package manifest (pacman + AUR)
├── bin/
│   ├── moonrice            the ecosystem CLI (palette/wallpaper/shell/media/...)
│   └── palettes.json       5 Material-tuned color schemes
├── config/
│   ├── hypr/
│   │   ├── hyprland.lua    Lua config (single entrypoint on Hyprland 0.56+)
│   │   ├── keymap.lua      all keybindings (single source of truth)
│   │   └── hyprland/       env, general, gestures, execs, rules, keybinds,
│   │                       variables, colors (generated), monitors (generated)
│   ├── moonshell/shell.json    shell: bar, dashboard, launcher, lock, OSD, notifs
│   ├── waybar/ swaync/ rofi/   lightweight fallback UI (kept, not autostarted)
│   ├── kitty/ mpv/ fuzzel/ swappy/   app configs
│   ├── starship.toml btop/ nvim/ yazi/ lazygit/ cmus/ fastfetch/ fetchx/
│   ├── xdg-desktop-portal/ fontconfig/ zshrc.d/
│   └── wallpapers/         5 themes × 2 resolutions
└── docs/                   architecture, install, keybinds, theming, faq

Components

• Shell — moonshell (Quickshell/Qt6, fork of caelestia-dots/shell): top bar with workspaces/tray/status icons, dashboard (media/performance/weather), launcher with actions, lock screen, OSD, notification center, sidebar, Nexus settings. Driven by Hyprland global shortcuts (global, moonshell:launcher, ...).
• Hyprland config (Lua only) — modular like caelestia-dots: env/execs/general/gestures/ rules/variables/colors + keymap.lua (single source of truth for every bind). User overrides: ~/.config/hypr/hypr-user.lua and ~/.config/moonrice/hypr-vars.lua (both auto-created, never overwritten).
• Theming — moonrice palette set <theme> rewrites Waybar, SwayNC, Rofi, Hyprland (Lua colors.lua + colors.conf for hyprlock), Kitty, Tmux, Zsh, Starship, Yazi, Lazygit, btop, Neovim — then live-reloads everything.
• Wallpaper engine — awww (primary, ~few MB) with swww/hyprpaper/swaybg fallbacks; wallpapers pulled from ~/Pictures/Wallpapers (same dir the shell uses).
• TUI-first — Kitty + yazi, nvim, lazygit, glow, cmus, btop, nmtui, qalc, cliphist, zoxide. Every GUI menu has a keyboard equivalent.
• Display management — install.sh detects the live layout and generates hyprland/monitors.lua (per-monitor workspace pinning: 1-3 / 4-6 / 7-9).
• Login screen (SDDM) — a custom moonrice greeter theme (based on sddm-astronaut-theme): blurred Material form, per-palette colors, and the same wallpaper you set on the desktop — moonrice wallpaper / moonrice palette set automatically sync the SDDM background (applies at next login). Preview with moonrice sddm test (sddm --test-mode).

Quick Start (any Arch/Debian/Fedora/openSUSE system)

git clone https://github.com/swadhinbiswas/moonrice ~/moonrice
cd ~/moonrice

./install.sh            # detects your OS → interactive full install
# or non-interactive:
./install.sh --apply-full       # packages + configs + moonshell
./install.sh --apply            # configs only
./install.sh --install-packages # just packages (OS-aware, per-distro names)
./install.sh --setup-shell      # moonshell: source build (quickshell + fork)
./install.sh --dry-run          # inspect the plan
./install.sh --rollback <stamp> # restore ~/.rice-backup/<stamp>

# then reboot / log in to Hyprland
moonrice doctor         # verify everything
moonrice palette set moon

The installer detects the distro (/etc/os-release), picks pacman/apt/dnf/zypper + sudo/doas, maps package names from packages.txt (per-distro columns) and installs everything in one run — with per-package fallback so a missing name never blocks the rest. Arch gets the full stack; other distros build quickshell + moonshell from source.

Keybind Cheat Sheet

The canonical keymap lives in one file — config/hypr/keymap.lua — and everything else (the Super+H rofi cheat sheet and this table) is generated from it. Never edit generated files by hand.

Keys	Action
Super (release) / Super+M / Super+D	Launcher
Super+Shift+S / Super+Shift+D / Super+Shift+B	Session menu / Dashboard / Sidebar
Super+U / Super+I / Super+Shift+K	Utilities / Nexus / Show all panels
Super+Return / Super+Alt+Return	Kitty / Scratchpad terminal
Super+E / Super+X / Super+B / Super+C	Yazi / nvim / browser / code
Super+Alt+G / Super+Alt+M / Super+Alt+X	Lazygit / cmus / glow
Super+A / Super+Shift+A	Actions menu / Mic toggle
Super+W / Super+Shift+W	Wallpaper select / random
Super+T / Super+V / Super+H	Theme switcher / Clipboard / Cheat sheet
Super+Shift+P / Super+Shift+N / Super+Shift+,	Play-pause / Next / Previous
Super+L / Super+Escape / Super+Shift+L	Lock / Lock / Suspend
F6 / Super+Ctrl+S / Super+Shift+C	Screenshot full / region / color picker
Super+1..0, Super+Shift+1..0	Workspaces / move window
Super+Ctrl+R / Ctrl+Super+Shift+R / Ctrl+Super+Alt+R	Reload / Kill / Restart shell
XF86*	Volume (OSD), brightness, kbd backlight, playback

Regenerate after editing keymap.lua:

scripts/gen-keyhints.sh config/hypr --markdown docs/KEYMAP.md

Full table: docs/KEYMAP.md (generated)

Design tokens

moonshell ships a full token system (rounding/spacing/padding/font sizes/ animation durations + easing curves). Defaults are compiled in moonshell/plugin/src/Moonshell/Config/tokens.hpp; override them in ~/.config/moonshell/shell-tokens.json (per-monitor: monitors/<screen>/shell-tokens.json). Shell-wide settings: ~/.config/moonshell/shell.json.

Plugins

Anything in ~/.config/hypr/plugins/ is loaded automatically:

• *.lua — loaded by hyprland.lua after the core modules (same hl.* API). Example: floating-utils.lua (float common dialogs).
• *.sh marked # AUTOSTART — started once at login by execs.lua (pgrep-guarded). Example: battery-warn.sh (low-battery daemon; only fires when the shell is down, the shell's native warnings cover the rest).

Nexus → Plugins page enables/disables them. Delete a file to disable a plugin.

Documentation

Page	What's in it
docs/index.md	Architecture and overview
docs/install.md	Installation, prerequisites & rollback
docs/keybinds.md	How the keymap pipeline works
docs/KEYMAP.md	Full generated keybind table
docs/theming.md	Palettes and the theme switcher
docs/troubleshooting.md	Common issues
docs/faq.md	Design decisions
docs/dev.md	Project structure

License

MIT © Swadhin Biswas. Caelestia shell is GPL-3.0 (see its repo). Compiled cursor theme is GPLv3 (Bibata derivative).