v1.0.1 • 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.
- 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.
- 3-Page Carousel Dashboard: Smooth spring physics expand the notch into a full 3-page command center:
- Page 1: Weather: 7-day forecast and hourly metrics powered by Open-Meteo with minimal obsidian vector SVGs (no generic emojis).
- Page 2: Control Center: Instant hover default with dynamic
$USER@$HOSTNAME, audio diagnostics, volume/brightness sliders, and quick toggles (DND, Night Light, Caffeine, Wi-Fi, Bluetooth). - Page 3: System Status & Process Network: Real-time CPU, RAM, GPU, storage metrics, and an embedded sub-page for live per-process network traffic 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.
- Native Wayland Layer Shell: High-performance obsidian glass dock built natively with Quickshell and Qt6 QML.
- Dynamic Window Tracking: Subscribes to
Hyprland.toplevelsto track active windows with dynamic running dots and active window highlights. - 3 Adaptive Visibility Modes:
- Always On: Sets exclusive zones to reserve desktop workspace margin.
- Auto Hide: Slides off-screen and smoothly reveals when cursor touches the 3px edge trigger strip.
- Smart Hide (Window Dodge): Intelligently stays visible on empty workspaces, then automatically slides off-screen when windows open.
- Obsidian Glass Context Menu: Right-click any app to toggle "Pin to Dock", launch a new instance, or close active windows.
- Settings Studio Customization: Configure dock position (Bottom, Top, Left, Right), opacity, icon sizes (32px - 64px), pill radius, hide delays, and hover physics (Parabolic Zoom, Float & Lift, Accent Glow, Flat) via the Quickshell Settings App (
DockSection.qml).
- 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.
- 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.gifusing hardware-acceleratedmpvpaper. - Wallhaven Integration: Search and sync toplist/hot community wallpapers directly into your local library.
- 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.
- 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.
| Shortcut | Action | Description |
|---|---|---|
| Super + Return | Terminal | Open Kitty terminal |
| Super + Space / Super + D | App Launcher | Open Quickshell application launcher |
| Super + Alt + Space | Toggle Dock | Show / hide Quickshell Application Dock |
| 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 |
| 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.
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
│ │ ├── py/weather.py # Open-Meteo weather fetcher & daemon
│ │ ├── sh/qs-dock.sh # Quickshell Dock lifecycle daemon
│ │ ├── sh/qs-island.sh # Dynamic Island controller
│ │ └── sh/qs-reload.sh # Quickshell & Island reload supervisor
│ └── Wallpaper/ # Static & Live wallpaper collections
├── quickshell/
│ ├── dock/ # Application Dock layer shell & context menu
│ ├── island/ # 3-Page Dynamic Island notch (Weather, Control, System)
│ ├── 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.1)
Note
AI coding assistants and contributors should refer to AGENTS.md for exhaustive details on project structure, QML theming contracts, state persistence, and script workflows before making modifications.
Hyprconf follows a clean release model (v1.0.1):
- 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
Contributions, bug reports, and suggestions are welcome!
- Read AGENTS.md to understand the architecture, state isolation, and styling standards.
- Fork the repository.
- Create a topic branch:
git checkout -b feature/my-enhancement. - Commit your changes:
git commit -m "feat: Add new feature". - Push to your fork and submit a Pull Request against the
mainor release branch.
- Shell Ninja — Concept, design, and implementation.
- Quickshell — Flexible Qt/QML desktop shell framework for Wayland.