Hyprconf — Minimalist Obsidian Hyprland & Quickshell Desktop

v1.0.0 • Crafted by Shell Ninja

A streamlined, obsidian-styled Hyprland desktop environment powered natively by Quickshell. Featuring an interactive morphing Dynamic Island notch, zero-latency Wayland layer shell integration, Material You (M3) / Noctalia wallpaper-derived color harmonizer, live video wallpapers (mpvpaper), and a unified system settings suite.

Note

This repository contains the core dotfiles and configurations. For initial system deployment and automatic dependency installation across Arch/CachyOS/Fedora, visit the hyprconf-install repository.

 Visual Showcase     Features     Shortcuts     Configuration     Updater     Contributing 

---

Visual Showcase

Desktop & Workspace Layout

Dynamic Island Command Center & Settings

Custom Application Launchers

Dynamic Theming & System Widgets

Morphing Lockscreen & Personalization Canvas

---

Key Features

Dynamic Island (quickshell/island)

• Adaptive Collapsed Notch: Floats cleanly at top-center (or bottom dock). Shows live CAVA audio visualizer wings during playback, track titles, active workspace dots, minimal clock, and battery/network badges.
• Morphing Dashboard: Smooth spring physics expand the notch into a full command center:
  • Overview: System volume, brightness, player controls, media cover art, and quick toggles (DND, Night Light, Performance profile, Wi-Fi, Bluetooth).
  • Status & Diagnostics: Real-time CPU, RAM, GPU, storage metrics, and 5-day weather forecasts.
  • Process Network Monitor: Live per-process bandwidth and socket tracking.
• Fullscreen Auto-Hide: Detects when games, media players, or browser F11 fullscreen modes are active, immediately unmapping the layer shell surface and releasing the exclusive zone so games and videos enjoy 100% unimpeded display.
• Native Polkit Agent: Password authorization flows morph seamlessly right out of the island notch.
• Quick Reload: Press Ctrl + Esc anytime to restart the Island and all desktop widgets.

Noctalia M3 Dynamic Colorscheme (hypr-colors.py)

• Wallpaper Hue Clustering: Groups wallpaper pixels into 24 discrete hue bins (15° separation) to discover contrasting color harmonies present in the image.
• 7 Authentic Variants:
  • Vibrant: Highest chroma saturation boost.
  • Muted: Soft, calm dominant background tones.
  • Expressive: Contrasting secondary pop tone (≥ 50° divergent hue).
  • Warm: Warmest amber, copper, and coral accents found in the image.
  • Cool: Deep blue, cyan, and glacial teal highlights.
  • Pastel: Soft, luminous high-lightness accent.
  • Original: Natural, raw sampled dominant color.
• System-Wide Hot Reload: Synchronously re-themes Hyprland window borders, Kitty terminal, Neovim, GTK3/GTK4, Qt6/KDE (Dolphin), Btop, and Quickshell widgets in real time.

Wallpaper & Live Media Selector (quickshell/island/WallpaperView.qml)

• Integrated Browser: Preview and select wallpapers directly within the expanded island.
• Color Variant Dropdown: Choose between the 7 Noctalia variants on the fly with live palette regeneration.
• Live / Video Wallpapers: Full support for .mp4, .webm, .mkv, and .gif using hardware-accelerated mpvpaper.
• Wallhaven Integration: Search and sync toplist/hot community wallpapers directly into your local library.

Custom App Launchers (quickshell/launcher)

• Style 1 (Slanted Split Quad) & Style 2 (Panoramic Grid): Fast, keyboard-navigable application launchers with live category filtering and terminal execution.
• Toggle between styles with Super + Alt + D.

Dynamic Island Lockscreen (quickshell/lockscreen)

• Expands directly out of the Dynamic Island notch into a fullscreen obsidian lockscreen upon Super + L.
• Smooth PAM authentication with whole-theme red shake on invalid password and reverse spring collapse upon unlock.

---

Essential Keyboard Shortcuts

Shortcut	Action	Description
Super + Return	Terminal	Open Kitty terminal
Super + Space / Super + D	App Launcher	Open Quickshell application launcher
Super + W	Wallpaper Picker	Open Quickshell Dynamic Island wallpaper selector
Ctrl + Esc	Reload Shell	Restart Quickshell & Dynamic Island
Super + F	Fullscreen	Toggle fullscreen mode (auto-hides island)
Super + Q	Close Window	Close active window
Super + E	File Manager	Open Dolphin / Thunar
Super + Shift + E	Yazi	Open terminal file manager
Super + V	Float Window	Toggle active window floating state
Super + X	Power Menu	Open Dynamic Island power & logout menu
Super + L	Lock Screen	Lock screen via Quickshell island morph
Print	Screenshot	Open Quickshell screenshot studio
Super + Shift + ,	Settings	Open Unified Quickshell Settings application
Super + Shift + H	Keybinds Help	Interactive keybinding search & dispatcher

Tip

Press Super + Shift + H anywhere to search all available keybindings interactively.

---

Configuration Architecture

All dotfiles reside under ~/.hyprconf/:

~/.hyprconf/
├── hypr/
│   ├── hyprland.conf          # Main entrypoint loader
│   ├── configs/               # Modular Lua configurations
│   │   ├── env.lua            # Environment variables & Wayland flags
│   │   ├── exec.lua           # Autostart daemons & background processes
│   │   ├── keybinds.lua       # Keybindings & window management
│   │   ├── windowrules.lua    # Window & layer rules
│   │   └── animations.lua     # Bezier curves and animation curves
│   ├── scripts/
│   │   ├── py/hypr-colors.py  # Noctalia M3 color harmony extraction engine
│   │   └── sh/qs-reload.sh    # Quickshell & Island reload supervisor
│   └── Wallpaper/             # Static & Live wallpaper collections
├── quickshell/
│   ├── island/                # Dynamic Island notch, HUD, & WallpaperView
│   ├── launcher/              # Custom app launcher (Style 1 & 2)
│   ├── lockscreen/            # Morphing PAM lockscreen
│   ├── widgets/               # Desktop System Monitor, Weather & Visualizer
│   ├── settings/              # Unified Hyprland & Quickshell Settings app
│   └── Theme.qml              # Live-reloaded reactive theme tokens
├── kitty/                     # Terminal configs & auto-synced colorscheme
├── nvim/                      # Neovim configuration & dynamic palette
└── .version                   # Active version release tag (v1.0.0)

---

Updates & Versioning

Hyprconf follows a clean release model (v1.0.0+):

• Background Watchdog: Runs automatically via hyprconf.sh --daemon, checking every 6 hours for new updates against shell-ninja/hyprconf.
• Notifications: When an update is detected, a desktop notification with an "Update Now" button and audio chime is sent.
• Manual Update: Run the interactive Gum-powered updater anytime:

  bash ~/.hyprconf/hypr/scripts/sh/hyprconf.sh

---

Contributing

Contributions, bug reports, and suggestions are welcome!

1. Fork the repository.
2. Create a topic branch: git checkout -b feature/my-enhancement.
3. Commit your changes: git commit -m "feat: Add new feature".
4. Push to your fork and submit a Pull Request against the development branch.

---

Acknowledgements & Credits

• Shell Ninja — Concept, design, and implementation.
• Quickshell — Flexible Qt/QML desktop shell framework for Wayland.