Documentation

🏠 Home

🏠 HorneroConfig - Comprehensive Dotfiles Framework

Docs | Changelog | Contributing

You might be here looking for (Linux) rice reference or to (full?) replicate my personal configuration of my favorite Window Managers and several apps as well. ⛄

HorneroConfig is your artisanal toolkit for crafting the perfect digital workspace. Named after the industrious hornero bird, renowned for its skillful nest-building, our framework empowers you to construct a robust, functional, and personalized computing environment.

Perfectly suited for a wide array of Desktop Environments and Window Managers, HorneroConfig thrives across different platforms including GitHub Codespaces, Gitpod, VS Code Remote - Containers, or even Linux distributions that are not Arch Linux.

Backed by the versatile Chezmoi, HorneroConfig stands out as a dotfiles manager that adapts flexibly to your needs, streamlining machine setup and ensuring consistency across devices. Embrace the spirit of the hornero, and let HorneroConfig transform your configurations into a harmonious blend of elegance and efficiency.

✨ Key Features

  • 🎨 Advanced Rice System: Switch between beautiful desktop themes instantly
  • 🧠 Smart Colors: Intelligent color adaptation for optimal readability and theme consistency
  • 🐚 Quickshell: Unified QML desktop shell (bar, launcher, dashboard, notifications, AI chat)
  • 🎨 Material Design 3: Intelligent color theming from wallpaper analysis
  • 🌊 Hyprland: Dynamic tiling Wayland compositor with smooth animations
  • 📦 Easy Management: Simple installation and configuration via chezmoi
  • 🔧 100+ Scripts: Comprehensive automation and utility scripts
  • 🔄 Automatic Theming: Seamless wallpaper-to-theme integration
  • 🛡️ Security: Built-in security auditing and hardening tools

Most were written from scratch. Core stack:

  • Compositor 🌊 Hyprland - Dynamic tiling Wayland compositor
  • Desktop Shell 🐚 Quickshell - Unified QML shell (bar, launcher, notifications, dashboard)
  • Launcher Fallback 🚀 terminal prompt - lightweight rescue launcher
  • Notifications 🔔 Built into Quickshell (replaces Mako)
  • Terminal Emulator 🐾 Kitty - GPU-accelerated terminal
  • Shell 🐚 Zsh with Powerlevel10k prompt
  • Lockscreen 🔒 Hyprlock - Secure lock screen
  • Wallpaper 🖼️ Quickshell + wpgtk integration via dots-wallpaper-set
  • File Manager 🃏 Thunar with customized side pane
  • and many more!

🚀 Installation & Performance

Chaotic-AUR Repository

HorneroConfig automatically configures the Chaotic-AUR repository during installation. This provides:

  • ⚡ Precompiled Binaries: Skip building AUR packages from source
  • 🎯 Faster Setup: Reduce installation time by 50-70%
  • 🔄 Regular Updates: Automatically maintained packages
  • 📦 Popular Packages: Hyprland + Quickshell ecosystem, pamac-aur, auto-cpufreq, and more

The repository is configured automatically by the chezmoi script at:

home/.chezmoiscripts/linux/run_onchange_before_install-000-chaotic-aur.sh.tmpl

For more information, visit the Chaotic-AUR documentation.

⚙️ Customization

🎨 Dotfiles Customization Guide

This repository is designed to be a starting point for your personalized dotfiles setup. You’re encouraged to fork it, adapt it to your needs, and maintain your own GitHub repository with your custom configurations.

[!TIP] The dotfiles use Chezmoi to manage, edit, and apply configuration changes across multiple machines — securely and efficiently.

🛠️ Getting Started with Customization

1. Fork This Repository

Create your own version of the dotfiles:

git clone https://github.com/<your-username>/dotfiles.git ~/.dotfiles

2. Initialize Chezmoi

[!IMPORTANT] This dotfiles setup includes references to my personal LastPass vault for storing sensitive information (like tokens or secrets).
If you plan to use or adapt these configs, make sure to replace or remove any references to LastPass and configure your own preferred secret management method — such as Bitwarden, 1Password, pass, gopass, or chezmoi's built-in encrypted secrets.
Double-check any scripts or encrypted templates (*.tmpl) before applying changes.

Link your forked dotfiles directory with chezmoi:

chezmoi init --source ~/.dotfiles

3. Edit Your Configurations

Use chezmoi’s built-in editing command:

chezmoi edit --source ~/.dotfiles

Make the changes that suit your preferences:

  • Theme and style adjustments
  • New keybindings
  • Custom scripts
  • Tool settings and plugins

4. Apply Your Changes

Once you're ready:

chezmoi apply --source ~/.dotfiles

All changes will be synced to your system.

📁 What You Can Customize

  • 🌊 Compositor settings (Hyprland)
  • 💻 Terminal experience (Zsh, Kitty)
  • 🎨 Theme and color schemes (Rofi, Waybar, Pywal)
  • 🛠️ Utility scripts (dots) and workflow helpers
  • 🔒 Security tools and system behaviors

[!TIP] Use chezmoi diff to preview your changes before applying.

🎨 Theming & Visual Customization

Smart Colors System

The dotfiles include an intelligent color system that automatically optimizes colors for any theme:

  • Semantic Colors: Error, success, warning, info colors that adapt to any palette
  • Theme Intelligence: Automatically selects optimal colors based on wallpaper
  • Application Integration: Works with Waybar, EWW, Hyprland, and custom scripts
  • Automatic Updates: Colors refresh automatically when changing wallpapers

Learn more: Smart Colors System

Rice Theme Management

🌍 Multi-Machine Consistency

One of the biggest advantages of using Chezmoi is portable configuration. You can sync your setup across multiple machines using a private or public GitHub repository.

Just run:

chezmoi init git@github.com:<your-username>/dotfiles.git
chezmoi apply

And your personalized setup will be ready!

🆘 Need Help?

Go ahead — personalize everything. Make your desktop, terminal, and tooling truly yours! 🚀

🎨 Rice System

Rice System: Theme Management

The rice system is now managed through the Quickshell-first appearance workflow.

Canonical Commands

dots appearance list
dots appearance current
dots appearance apply neon-city
dots appearance set-variant vibrant
dots appearance set-mode dark
dots appearance set-wallpaper /path/to/wallpaper.jpg

dots rice ... is retained as compatibility naming, but dots appearance ... is the canonical interface.

What a Rice Controls

  • wallpaper selection
  • smart-colors / M3 palette generation
  • light/dark mode and M3 variant
  • GTK theme metadata and optional extras
  • Quickshell-facing appearance state

Quickshell Integration

Appearance changes done from the control center can be previewed first, then committed with Apply/Save.

flowchart LR
  user[UserSelectsAppearance] --> preview[QuickshellPreview]
  preview --> apply[ApplyOrSave]
  apply --> cli[dots-appearanceApply]
  cli --> palette[dots-smart-colorsAndScheme]
  palette --> shell[QuickshellReload]

Structure

Rices live under:

~/.local/share/dots/rices/<rice-name>/

Typical files:

  • config.sh
  • executable_apply.sh
  • backgrounds/
  • optional preview.*

Notes

  • Legacy Rofi/JGMenu theme selectors were removed from the maintained path.
  • The maintained desktop path is Hyprland + Quickshell.

🧠 Smart Colors System

Smart Colors System

Smart Colors generates semantic colors and Material Design 3 palettes from the current wallpaper, then keeps Quickshell synchronized.

Primary Contract

  • Quickshell is the main consumer through ~/.cache/dots/smart-colors/scheme.json.
  • dots-wal-reload and dots-wallpaper-set trigger palette refresh and Quickshell IPC reload.
  • Script consumers can source shell/env exports from the same cache directory.

Wallpaper Pipeline Contract

Historical pipelines

  • wpgtk pipeline: wpg -s <image> -> wpg.conf runs dots-wal-reload and refreshes shell colors.
  • Legacy Quickshell direct pipeline: UI actions used to call compositor-specific wallpaper setters directly, bypassing wpg and global reload orchestration.

The direct pipeline could desynchronize ~/.config/wpg/.current from shell/runtime state and miss some app reloads that are centralized in dots-wal-reload.

Unified contract

  • Use dots-wallpaper-set as the single entrypoint for wallpaper changes from shell UI/actions.
  • When wpg is available, dots-wallpaper-set delegates to wpg -s so wpgtk remains source-compatible.
  • Wallpaper resolution priority is unified across scripts:
    1. Explicit argument
    2. ~/.local/state/dots/wallpaper/path (canonical persistent pointer; respects DOTS_STATE_DIR / XDG_STATE_HOME)
    3. ~/.cache/wal/wal (pywal)
    4. ~/.config/wpg/.current (optional, when using wpgtk)

Main Commands

dots-smart-colors --generate --m3
dots-smart-colors --analyze
dots-smart-colors --concept=error
dots-wal-reload

Generated Cache

All generated files are written to ~/.cache/dots/smart-colors/.

Core files:

  • scheme.json (Quickshell M3 palette)
  • colors.sh (shell variables for scripts)
  • colors.env (export-friendly environment file)
  • colors-hyprlock.env (lockscreen integration)
  • colors-kitty.conf (terminal integration)
  • colors.css (generic CSS variables)

Compatibility files may exist for external tooling, but they are not part of the primary UX contract.

Data Flow

flowchart LR
  wallpaper[WallpaperChange] --> set[dots-wallpaper-set]
  set --> wal[dots-wal-reload]
  wal --> smart[dots-smart-colorsGenerate]
  smart --> scheme[schemeJson]
  scheme --> colours[QuickshellColoursService]
  colours --> ui[QuickshellUIUpdated]

Troubleshooting

# Rebuild smart-colors cache
dots-smart-colors --generate --m3

# Confirm cache files exist
ls -la ~/.cache/dots/smart-colors/

# Force shell-side reload path
dots-quickshell ipc colours reload

Notes

  • Legacy Waybar/EWW/Rofi integrations are no longer part of the maintained path.
  • The supported default stack is Hyprland + Quickshell.

🪟 Window Managers Overview

🪟 Hyprland Configuration Guide

This guide provides an overview of how to customize Hyprland, the dynamic tiling Wayland compositor used in this dotfiles setup.

[!TIP] Everything is fully customizable — from layout and keybindings to appearance and startup behavior. All configurations are version-controlled using chezmoi, making it easy to manage and sync.

🧱 General Customization Workflow

The general process is:

  1. Locate the config directory
  2. Edit files with chezmoi edit
  3. Apply changes with chezmoi apply
  4. Restart Hyprland or reload configurations

🌊 Hyprland Configuration

📁 Config Path: ~/.config/hypr

The Hyprland configuration controls:

  • Keybindings
  • Window rules and behavior
  • Workspace layout
  • Animations and effects
  • Wayland-specific settings

To edit:

chezmoi edit ~/.config/hypr/hyprland.conf
chezmoi apply

For more info, check the Hyprland documentation.

🔧 Pro Tips

  • Add compositor-specific autostart scripts
  • Use Quickshell as the primary shell (bar/launcher/dashboard/control center)
  • Keep launcher and power keybinds routed through dots-quickshell ipc ...
  • Use chezmoi diff to preview config changes

🆘 Need Help?

If you run into issues or want to go deeper:

Customizing your compositor is one of the best ways to boost your productivity and tailor your desktop to your style — make it yours! 🎨

⌨️ Hyprland Keybindings

Hyprland Keybindings

Complete reference for all keybindings in HorneroConfig's Hyprland setup.

Applications and Utilities

Keybinding Function
Super+Return Terminal (Kitty)
Super+D Application launcher (Quickshell)
Alt+Ctrl+C Clipboard manager (dots-clipboard)
Super+? or Super+/ Keyboard shortcuts help overlay (dots-keyboard-help)
Super+Ctrl+Space AI assistant (sgpt via IBus)
Super+Shift+Tab Task switcher (dots-snappy-switcher prev)
Super+E File manager (Thunar)
Super+Shift+S Screenshot tool (grimblast/grim)
Print Screenshot (area selection)

Window Management

Keybinding Function
Super+Q Close focused window
Super+Shift+Q Kill focused window (force)
Super+F Toggle fullscreen
Super+Shift+F Smart floating (toggle + center + resize)
Super+Shift+Space Focus toggle (floating ↔ tiled)
Super+Ctrl+C Center floating window
Super+Space Toggle tiling/floating
Super+P Focus parent (group)
Super+C Focus child (group)
Super+U Promote focused window to its own column (scrolling layout)
Super+' Toggle focus fit mode (center ↔ fit)
Super+Ctrl+W Toggle layout profile (scrolling ↔ dwindle)
Super+Ctrl+Shift+W Force scrolling profile
Super+Ctrl+Alt+W Force dwindle profile

Window Focus

Keybinding Function
Super+H / Super+Left Focus window left
Super+J / Super+Down Focus window down
Super+K / Super+Up Focus window up
Super+L / Super+Right Focus window right

Window Movement

Keybinding Function
Super+Shift+H / Super+Shift+Left Move window left
Super+Shift+J / Super+Shift+Down Move window down
Super+Shift+K / Super+Shift+Up Move window up
Super+Shift+L / Super+Shift+Right Move window right

Window Resizing

Keybinding Function
Super+R Enter resize mode
Super+Ctrl+H Resize shrink width
Super+Ctrl+J Resize grow height
Super+Ctrl+K Resize shrink height
Super+Ctrl+L Resize grow width

Workspace Navigation

Keybinding Function
Super+1-9,0 Switch to workspace 1-10
Super+KP_1-9,0 Switch to workspace 1-10 (numpad)
Super+Alt+Left Previous active workspace
Super+Alt+Right Next active workspace
Super+Ctrl+Left Previous existing workspace
Super+Ctrl+Right Next existing workspace
Super+Tab Cycle through workspaces

Window to Workspace

Keybinding Function
Super+Shift+1-9,0 Move window to workspace 1-10
Super+Shift+KP_1-9,0 Move window to workspace 1-10 (numpad)

Scratchpad

Keybinding Function
Super+Z Toggle scratchpad visibility
Super+Shift+Z Move window to scratchpad

Scrolling Layout (Niri-style)

Keybinding Function
Super+Alt+H Move layout viewport one column to the left
Super+Alt+L Move layout viewport one column to the right
Super+Alt+, Swap active column with left neighbor
Super+Alt+. Swap active column with right neighbor
Super+Alt+- / Super+Alt+= Decrease/increase column width preset
Super+Alt+Shift+- / Super+Alt+Shift+= Fine resize column width
Super+Alt+F Fit active column into view
Super+Alt+Shift+F Fit visible columns into view

Gaps Control

Keybinding Function
Super+G, + Increase gaps
Super+G, - Decrease gaps
Super+G, 0 Reset gaps to default
Super+G, Shift+0 Remove all gaps

System Controls

Keybinding Function
Super+Ctrl+P Toggle Bar (Quickshell)
Super+Ctrl+M Toggle Notification Center (Quickshell)
Super+Shift+R Reload Hyprland configuration
Super+Shift+E Exit Hyprland
Super+X System power menu (Quickshell)
Super+L Lock screen (Hyprlock)

Media Controls

Keybinding Function
XF86AudioPlay Play/pause media
XF86AudioPause Pause media
XF86AudioNext Next track
XF86AudioPrev Previous track
XF86AudioStop Stop playback

Volume Controls

Keybinding Function
XF86AudioRaiseVolume Increase volume (+1%)
XF86AudioLowerVolume Decrease volume (-1%)
XF86AudioMute Toggle mute
XF86AudioMicMute Toggle microphone mute

Brightness Controls

Keybinding Function
XF86MonBrightnessUp Increase brightness
XF86MonBrightnessDown Decrease brightness

Mouse Bindings

Action Function
Super+Left Click Move window
Super+Right Click Resize window
Super+Middle Click Toggle floating

Special Modes

Resize Mode (Super+R)

Once in resize mode:

  • H / Left - Shrink width
  • J / Down - Grow height
  • K / Up - Shrink height
  • L / Right - Grow width
  • Escape / Return - Exit resize mode

Gaps Mode (Super+G)

Interactive gaps adjustment:

  • + / = - Increase gaps
  • - - Decrease gaps
  • 0 - Reset to default
  • Shift+0 - Remove all gaps
  • Escape / Return - Exit gaps mode

Configuration Files

Keybindings are organized in:

~/.config/hypr/hyprland.conf.d/
├── keybindings.conf           # Core keybindings
├── keybindings-media.conf     # Media and volume controls
└── keybindings-custom.conf    # User customizations

Customization

To add custom keybindings, edit:

~/.config/hypr/hyprland.conf.d/keybindings-custom.conf

Example:

# Custom application launcher
bind = $Mod, B, exec, firefox

# Custom window manipulation
bind = $Mod SHIFT, M, togglesplit

Tips

  • Modkey: Super (Windows key) is the primary modifier
  • Consistent with Vim: H J K L for directional movement
  • Arrow keys work: All directional bindings have arrow key alternatives
  • Numpad support: Full numpad support for workspace switching
  • Adaptive: Smart floating automatically centers and resizes windows appropriately

🔒 Lockscreen

Lockscreen System

Wayland-native lockscreen management with hyprlock
Alternative to betterlockscreen for Wayland/Hyprland environments

Overview

dots-lockscreen provides a Wayland-compatible lockscreen solution using hyprlock. It processes wallpapers with various visual effects and integrates with the dots ecosystem's smart color system.

Features

  • Multiple Effects: dim, blur, dimblur, pixel
  • Smart Color Integration: Automatically uses colors from the smart-colors system
  • Cached Images: Pre-generates lockscreen images for instant locking
  • ImageMagick Processing: Creates professional-looking lockscreen backgrounds
  • Graceful Fallbacks: Falls back to base image if effect images aren't available

Installation

The lockscreen system is automatically installed when you apply the dotfiles with chezmoi. The installation script is located at:

home/.chezmoiscripts/linux/run_onchange_before_install-hyprland.sh.tmpl

It installs:

yay -S --noconfirm --needed hyprlock hypridle

Usage

Update Lockscreen Images

Generate lockscreen images from a wallpaper:

dots lockscreen --update=/path/to/wallpaper.png

With custom effects parameters:

dots lockscreen --update=/path/to/wallpaper.png --dim=50 --blur=7 --pixel=15

Lock the Screen

Lock with default blur effect:

dots lockscreen --lock
dots lockscreen -l

Lock with specific effect:

dots lockscreen --lock --lock-effect=dim
dots lockscreen --lock --lock-effect=blur
dots lockscreen --lock --lock-effect=dimblur
dots lockscreen --lock --lock-effect=pixel

Automatic Updates

The lockscreen is automatically updated when you change wallpapers using:

dots wal-reload

Effects

Dim

Darkens the wallpaper by a specified percentage (default: 40%)

dots lockscreen --update=wallpaper.png --dim=60

Blur

Applies Gaussian blur to the wallpaper (default level: 5)

dots lockscreen --update=wallpaper.png --blur=7

DimBlur

Combines dimming and blurring for a professional look

dots lockscreen --update=wallpaper.png --dim=40 --blur=5

Pixel

Creates a pixelated/mosaic effect (default scale: 10)

dots lockscreen --update=wallpaper.png --pixel=15

Configuration

Cache Directory

Lockscreen images are stored in:

~/.cache/dots-lockscreen/current/
├── lock_resize.png    # Base resized image
├── lock_dim.png       # Dimmed version
├── lock_blur.png      # Blurred version
├── lock_dimblur.png   # Dim + blur version
└── lock_pixel.png     # Pixelated version

Smart Colors

The lockscreen automatically uses colors from:

~/.cache/dots/smart-colors/current.env

Colors used:

  • SMART_BG: Background color
  • SMART_FG: Foreground/text color
  • SMART_PRIMARY: Ring color
  • SMART_ACCENT: Accent color
  • SMART_SUCCESS: Correct password indicator
  • SMART_ERROR: Wrong password indicator

Integration

EWW Powermenu

The lockscreen is integrated into the EWW powermenu:

(defwidget lock []
  (box :class "genwin" :vexpand "false" :hexpand "false"
    (button :class "btn_lock"
            :onclick "~/.local/bin/dots-power-menu --mode=minimal; dots-lockscreen -l blur"
            "")))

Wal Reload

Automatically updates lockscreen when changing themes:

dots wal-reload  # Updates wallpaper and lockscreen

Rice System

Rice themes can trigger lockscreen updates in their apply.sh:

if command -v dots-lockscreen &>/dev/null; then
  dots-lockscreen --update="$wallpaper"
fi

Hyprlock Configuration

The script dynamically generates a hyprlock configuration with these features:

background {
  path = <effect-image>
  blur_passes = 3
  blur_size = 7
  contrast = 0.8916
  brightness = 0.8172
  vibrancy = 0.1696
}

input-field {
  size = 300, 60
  outline_thickness = 2
  outer_color = rgba(<primary-color>)
  inner_color = rgba(<bg-color>)
  font_color = rgba(<fg-color>)
  fail_color = rgba(<error-color>)
  # ... and more
}

Rice-Style-Aware Layouts

The lockscreen automatically adapts its layout based on your current rice's RICE_STYLE. This provides a cohesive aesthetic experience across your entire desktop.

Available Layouts

Layout Rice Styles Description
Default Any unlisted style Clean, centered layout with standard typography
Cyberpunk cyberpunk, neon, futuristic Glowing neon elements, tech-inspired fonts
Cozy cozy, kawaii, cute, warm Soft, rounded elements with pastel accents
Vaporwave vaporwave, retro, synthwave Gradient effects, 80s-inspired typography
Minimal minimal, clean, productive Ultra-clean with minimal UI elements

How It Works

  1. When locking, the script reads RICE_STYLE from your current rice's config.sh
  2. Based on the style, it selects the appropriate layout template
  3. Colors are pulled from the smart-colors cache
  4. The hyprlock configuration is generated dynamically

Rice Configuration

To enable style-aware layouts, add RICE_STYLE to your rice's config.sh:

# Example for cyberpunk rice
RICE_STYLE="Cyberpunk"

# Example for cozy rice
RICE_STYLE="Cozy"

The style matching is case-insensitive and supports partial matches (e.g., "cozy warm" matches the Cozy layout).

Comparison with Betterlockscreen

Feature betterlockscreen dots-lockscreen
Platform X11 (i3lock) Wayland (hyprlock)
Effects 6 effects 4 core effects
Multi-monitor Native support Via hyprlock
Color integration Manual config Smart-colors system
Dependencies i3lock-color, imagemagick hyprlock, imagemagick
Login box Custom rendering Hyprlock built-in

Troubleshooting

Lockscreen doesn't show colors

Ensure smart-colors cache exists:

dots smart-colors analyze
dots wal-reload

Images not generating

Check ImageMagick installation:

magick --version
# or
convert --version

Hyprlock not found

Install hyprlock:

yay -S hyprlock

Lock command fails

Generate lockscreen images first:

dots lockscreen --update=~/.local/state/dots/wallpaper/path

Dependencies

  • hyprlock (required)
  • imagemagick (required)
  • jq (for resolution detection)
  • hyprctl (for Hyprland display info)

Files

  • Script: ~/.local/bin/dots-lockscreen
  • Cache: ~/.cache/dots-lockscreen/current/
  • Current wallpaper pointer: ~/.local/state/dots/wallpaper/path
  • Smart colors: ~/.cache/dots/smart-colors/current.env

See Also

🐚 Quickshell Shell

🐚 Quickshell: Desktop Shell

Quickshell is the unified desktop shell for HorneroConfig, built with QML/QtQuick. It provides a cohesive, themeable, and extensible desktop experience.

[!TIP] Quickshell integrates with Material Design 3 theming, automatically adapting all UI elements to your wallpaper's color palette.

📋 Overview

Quickshell provides all desktop shell functionality through modular QML components:

Module Description
Left Rail Bar Vertical/horizontal rail with workspaces, clock, status icons, power
Launcher App search, calculator, wallpaper browser, appearance selector
Dashboard Tabbed system overview, media, performance, weather
Notifications Popup notifications and notification center sidebar
Session Rail Right-edge quick actions menu (logout, power, session controls)
Lock PAM-authenticated lock screen
OSD Notch Right-edge sliders for volume/brightness feedback
AI Chat Multi-provider AI assistant sidebar
Background Desktop wallpaper with optional audio visualizer
AreaPicker Screenshot region selector
Utilities Quick toggles panel (WiFi, Bluetooth, DND, etc.)

🚀 Management

Use the dots-quickshell script to manage the shell:

dots quickshell start               # Start Quickshell
dots quickshell stop                # Stop Quickshell
dots quickshell restart             # Restart Quickshell
dots quickshell status              # Check if running
dots quickshell preset list         # List shell presets
dots quickshell preset apply <name> # Apply shell preset
dots quickshell config get bar.position

IPC Commands

dots-quickshell ipc colours reload    # Reload color scheme
dots-quickshell ipc bar toggle        # Toggle bar visibility
dots-quickshell ipc dashboard toggle  # Toggle dashboard
dots-quickshell ipc launcher toggle   # Toggle launcher
dots-quickshell ipc session toggle    # Toggle session/power menu
dots-quickshell ipc sidebar toggle    # Toggle notification sidebar

Note: drawer toggles are routed through Quickshell's drawers IPC target internally by dots-quickshell, so the commands above are the stable public interface you should keep using.

🎨 Theming

Quickshell uses Material Design 3 (M3) color palettes generated from your wallpaper:

Color Pipeline

  1. Wallpaper change triggers dots-smart-colors --m3
  2. generate-m3-colors.py extracts M3 palette using python-materialyoucolor
  3. Palette saved to ~/.cache/dots/smart-colors/scheme.json
  4. Quickshell's Colours service watches the file and reloads automatically

Scheme Configuration

Each appearance (rice) can configure its M3 scheme via config.sh:

SCHEME_TYPE="vibrant"     # tonalSpot, vibrant, expressive, neutral, monochrome, fidelity
DARK_MODE="true"          # true/false
ACCENT_COLOR=""           # Optional hex color override
BAR_POSITION="top"        # top/bottom

Appearance Commands

dots appearance list
dots appearance current
dots appearance apply machines
dots appearance set-variant tonalspot
dots appearance set-mode light

🏗️ Architecture

Unified Drawers Model

The active shell now follows a unified drawers architecture inspired by reference/shell:

  • A dedicated drawers layer (modules/drawers/Drawers.qml) owns interaction orchestration.
  • Edge exclusion windows (modules/drawers/Exclusions.qml) reserve space in Hyprland.
  • A global rounded desktop frame (modules/drawers/BorderFrame.qml) provides shell chrome.
  • Bar behavior is split into content and wrapper:
    • modules/bar/BarContent.qml
    • modules/bar/BarWrapper.qml
  • Drawers interaction surface (modules/drawers/Interactions.qml) handles hover/wheel behavior.

Services Layer

QML singletons providing system integration:

Service Purpose
Colours M3 theming, transparency, wallpaper luminance
Hypr Hyprland IPC (workspaces, monitors, keyboard)
Audio PipeWire audio, Cava visualization, beat detection
Players MPRIS media player control
Brightness Screen brightness (brightnessctl, ddcutil)
Network WiFi/Ethernet management (nmcli)
SystemUsage CPU, GPU, memory, disk monitoring
Weather Open-Meteo weather data
Wallpapers Wallpaper browsing and selection
Notifs Notification server (replaces Mako)
Time System clock and date
Visibilities Panel visibility state management
Ai Multi-provider AI with function calling

C++ Plugin (Hornero)

Performance-critical components built with CMake:

  • ImageAnalyser — Wallpaper luminance for dynamic transparency
  • Qalculator — Mathematical expression evaluation (libqalculate)
  • AppDb — Application frequency tracking (SQLite)
  • Toaster — Toast notification management
  • Requests — HTTP client for QML
  • AudioCollector — PipeWire audio capture
  • BeatTracker — Beat detection (aubio)
  • CavaProvider — Audio visualization (cava)
  • FileSystemModel — Filesystem browsing for QML
  • CachingImageManager — Image caching from QML items

Configuration

Shell behavior is configured via ~/.config/hornero/shell.json:

{
  "border": { "thickness": 2, "rounding": 24 },
  "bar": {
    "position": "left",
    "showOnHover": false,
    "sizes": { "innerWidth": 48 }
  },
  "appearance": {
    "animations": {
      "duration": 200,
      "durations": { "small": 160, "normal": 220, "large": 320 }
    }
  }
}

Reference Parity Status

  • Matched: wallpaper-driven M3 theming pipeline, left-rail shell feel, top control center, launcher command modes, right-edge OSD/session controls, rounded frame and edge exclusions.
  • Intentional deviations: Hornero-specific dots-* integrations, rice selector mode in launcher, AI chat module.
  • In progress hardening: deeper panel unification and additional popout parity refinements.

⌨️ Keybindings

Keybinding Action
Super+D Toggle launcher
Super+X Toggle session/power menu
Super+Ctrl+B Toggle bar
Super+? or Super+/ Keyboard shortcuts help

📂 File Structure

~/.config/quickshell/
├── shell.qml              # Main entry point
├── config/
│   └── Config.qml         # Configuration singleton
├── services/              # System integration singletons
│   ├── Colours.qml        # M3 theming
│   ├── Hypr.qml           # Hyprland IPC
│   ├── Audio.qml          # Audio management
│   └── ...
├── modules/               # UI components
│   ├── bar/               # Status bar
│   ├── launcher/          # App launcher
│   ├── dashboard/         # System dashboard
│   ├── notifications/     # Notification system
│   ├── session/           # Power menu
│   ├── lock/              # Lock screen
│   ├── osd/               # On-screen display
│   ├── aichat/            # AI assistant
│   ├── sidebar/           # Notification sidebar
│   ├── background/        # Desktop background
│   ├── areapicker/        # Screenshot selector
│   └── utilities/         # Quick toggles
├── utils/                 # Shared utilities
│   ├── Paths.qml
│   ├── Icons.qml
│   ├── SysInfo.qml
│   └── Strings.qml
└── plugin/                # C++ plugin (built by Chezmoi)
    ├── CMakeLists.txt
    └── src/Hornero/

🔧 Troubleshooting

Quickshell not starting

# Check if already running
dots-quickshell status

# Check for errors
quickshell 2>&1 | head -50

# Ensure plugin is built
ls ~/.local/lib/quickshell/qml/Hornero/

Colors not updating

# Regenerate M3 palette
dots-smart-colors --m3

# Check scheme.json exists
cat ~/.cache/dots/smart-colors/scheme.json | head

# Force reload
dots-quickshell ipc colours reload

Plugin build fails

# Ensure build deps are installed
yay -S --needed cmake ninja qt6-base qt6-declarative aubio cava pipewire

# Rebuild manually
cd ~/.config/quickshell/plugin
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build --prefix ~/.local/lib/quickshell

📚 Related Documentation

✅ Quickshell Parity Checklist

Quickshell Parity Checklist

Use this checklist after each substantial shell change.

Apply and restart

cd ~/.dotfiles
chezmoi apply --source=. --force
dots-quickshell restart

Hyprland layout and exclusions

  • [ ] Left rail does not overlap client windows.
  • [ ] Top/bottom bar modes reserve space correctly (no window content under bar).
  • [ ] Rounded desktop frame is visible on all monitors.
  • [ ] Right-edge notch panels open inside shell frame and do not clip incorrectly.

Core interaction flow

  • [ ] dots-quickshell ipc launcher toggle opens/closes launcher.
  • [ ] dots-quickshell ipc dashboard toggle toggles top control center.
  • [ ] dots-quickshell ipc session toggle opens right quick actions rail.
  • [ ] Scroll over rail triggers configured volume/brightness action.
  • [ ] Escape closes temporary overlays/popouts where expected.

Popouts and side controls

  • [ ] Audio/network/bluetooth/battery popouts align to bar position.
  • [ ] Popouts never render detached off-screen.
  • [ ] OSD appears on right edge and updates for volume/brightness changes.

Theming and wallpaper pipeline

  • [ ] dots-smart-colors --m3 regenerates ~/.cache/dots/smart-colors/scheme.json.
  • [ ] dots-quickshell ipc colours reload updates shell palette live.
  • [ ] Wallpaper changes update ~/.local/state/dots/wallpaper/path.
  • [ ] Light/dark mode follows generated scheme and keeps readable contrast.

Notifications and session

  • [ ] Notifications stack at top-right and keep shell style.
  • [ ] Session buttons execute expected commands (logout/power/reload).

Regression checks

  • [ ] No duplicate IPC handler warnings at startup.
  • [ ] No missing file warnings for battery/lock LEDs on current hardware.
  • [ ] No missing dependency crash when optional tools are absent (ddcutil, etc.).

📁 Thunar File Manager

Thunar Side Panel (Static Bookmarks)

The Thunar side panel (GTK bookmarks) is managed directly via a versioned template in this repository. No generation script is used: what you see in the template is what gets deployed.

File Deployed

Runtime location: ~/.config/gtk-3.0/bookmarks

Source template: home/dot_config/gtk-3.0/bookmarks.tmpl

Managed Section

Inside the template there is a clearly delimited block:

## BEGIN MANAGED SECTION
... lines ...
## END MANAGED SECTION

Edit that block in the template only (not in-place after deployment) to keep changes tracked. Anything you add BELOW the END marker (in your local deployed file) will persist across future template edits, because chezmoi will treat local modifications outside the managed lines as user changes unless you force overwrite. If you want fully reproducible state, keep all bookmarks inside the managed block and re-apply.

Custom Bookmarks

Add personal, machine‑specific bookmarks below the managed section directly in ~/.config/gtk-3.0/bookmarks. Example lines:

file:///mnt/storage  🗄 Storage
smb://nas.local/share  🌐 NAS Share

Removing Emojis

If you prefer a minimalist look, edit the template and delete the emoji / icon column (they are just literal characters). Re-apply with:

chezmoi apply --force --include=files

The template includes: Home, Projects, Dev, Downloads, Documents, Pictures, Music, Videos, .config, LocalShare, Rices, Wallpapers, Bin. Remove or reorder directly in the template to reflect your workflow.

Adding Per-Rice Bookmarks (Optional Manual Pattern)

If a specific rice needs additional paths (e.g. a theme assets folder), just append them manually after switching rice. Since we removed automation, we intentionally keep this lightweight. If automation becomes desirable again, a simple helper script or a chezmoi data-driven conditional can be reintroduced later.

Keeping Things Clean

If a bookmarked directory no longer exists, Thunar will still show it (but inaccessible). Periodically prune obsolete lines manually. You can safely create missing directories with:

mkdir -p ~/Projects ~/Dev ~/.local/share/dots/rices ~/.local/share/wallpapers

Restoring / Resetting

Accidentally broke the file? Just re-apply:

chezmoi apply --force --include=files

Font / Emoji Issues

If emojis appear as empty squares, install a font with emoji coverage (e.g. Noto Color Emoji or a Nerd Font variant) or remove the symbols.

Future Enhancements (Optional Ideas)

  • Folder-specific icons using .directory files
  • Conditional entries via Go template (per host / per rice)
  • Color-tag comments referencing Smart Colors system

For now the approach stays intentionally simple: a single, explicit source of truth under version control.

📁 Yazi File Manager

Yazi File Manager

Yazi is a blazing-fast terminal file manager written in Rust, with async I/O and native Kitty image previews. It replaces ranger in HorneroConfig with better performance, simpler theming, and built-in archive/media support.

Quick Start

# Open yazi in current directory
dots yazi

# Open yazi and cd to last directory on exit
dots yazi --last-dir

# Or use the shell alias
ycd

# Show keybinding cheatsheet
dots yazi --cheatsheet

# Check preview dependencies
dots yazi --fix-previews

Configuration

All config lives in ~/.config/yazi/:

File Purpose
yazi.toml General settings, openers, preview config
keymap.toml Custom keybindings (layered on defaults)
theme.toml Color scheme / flavor selection
init.lua Lua plugin hooks

Key Settings (yazi.toml)

  • Miller columns: ratio = [2, 4, 4] (parent, current, preview)
  • Hidden files: show_hidden = true
  • Sort: sort_by = "natural", directories first
  • Previews: Kitty protocol auto-detected, quality 75

Openers

Files open with xdg-open by default. Directories can also open in Thunar. Text files open in $EDITOR.

Keybindings

Key Action
h / l Parent / Enter directory
j / k Move down / up
~ Go home
. Toggle hidden files

Quick Directories (g + key)

Key Directory
gh Home
gp ~/Projects
gd ~/Downloads
gD ~/Documents
gP ~/Pictures
gm ~/Music
gv ~/Videos
gc ~/.config
gl ~/.local
gr Rices directory
gw Current rice wallpapers
gb ~/.local/bin (scripts)
gt /tmp

File Operations

Key Action
Space Toggle select
y Copy (yank)
x Cut
p Paste
a Create file/dir
r Rename
d Trash
DD Safe trash (confirm)
yp Yank path to clipboard
yd Yank directory to clipboard
yn Yank filename to clipboard

Power Features

Key Action
f Filter files
/ Search
z Jump with zoxide
Z Jump with fzf
C Compress selection
X Extract archive
Alt-t Open in Thunar
s Shell command

Sorting (o + key)

Key Sort by
on Name
os Size
om Modified
ot Type
oe Extension
or Reverse

Smart Colors Integration

Yazi inherits terminal colors via escape sequences. When you switch rice themes:

  1. dots-wal-reload regenerates pywal colors
  2. Terminal (Kitty) receives new color palette
  3. Yazi automatically picks up the new colors

No custom colorscheme file is needed (unlike ranger). The theme.toml uses Catppuccin flavors as a base, with terminal colors taking priority.

Image Previews

Yazi uses native Kitty image protocol for previews. Requirements:

  • Kitty terminal (v0.28.0+) -- automatic, no configuration needed
  • ffmpegthumbnailer -- video thumbnails
  • poppler (pdftoppm) -- PDF previews
  • imagemagick -- image conversion

Run dots yazi --fix-previews to check all dependencies.

Shell Integration

The ycd alias (defined in .zsh_aliases) launches yazi and changes your shell directory to wherever you navigated when you quit:

ycd              # launch yazi, cd on exit
ycd ~/Projects   # start in specific directory

The Super+E keybinding in Hyprland opens yazi in a floating popup window.

Dots Integration

  • Wrapper script: dots-yazi (or dots yazi)
  • Hyprland keybinding: Super+E opens yazi popup
  • Thunar context menu: "Open in Yazi" right-click option
  • Waybar: yazi popup windows get file manager icon
  • Smart colors: automatic terminal color inheritance

Troubleshooting

Images not previewing

dots yazi --fix-previews

Check that you are running inside Kitty terminal. Other terminals may need ueberzugpp.

Colors look wrong

Ensure pywal/smart-colors are generating terminal colors:

dots-wal-reload

Plugins not loading

ya pkg install    # Install all locked plugins
ya pkg upgrade    # Upgrade plugins

📋 CopyQ Clipboard Manager

📋 CopyQ Clipboard Manager Customization

CopyQ is a powerful clipboard manager integrated with HorneroConfig's smart-colors system, providing theme-adaptive styling that automatically matches your current color scheme.

[!TIP] CopyQ automatically adapts to your current theme colors when you change wallpapers via wpg or run dots-wal-reload.

🎨 Visual Customization

Smart Colors Integration

CopyQ's appearance is automatically themed using the smart-colors system:

  • Automatic Theme Adaptation: Colors update when you change wallpapers
  • Semantic Colors: Uses theme-adaptive error, warning, success, info, and accent colors
  • Consistent Design: Follows HorneroConfig design principles (rounded corners, spacing, etc.)

Design Principles

The CopyQ theme follows HorneroConfig's visual guidelines:

  • Rounded Corners: 12px border-radius matching Hyprland decoration
  • Consistent Spacing: 8px padding and margins for comfortable UI
  • Smooth Transitions: 0.2s ease transitions for interactive elements
  • Theme-Adaptive Colors: All colors adapt to light/dark themes automatically

⚙️ Configuration

Files Location

  • Configuration: ~/.config/copyq/copyq.conf (managed by chezmoi)
  • Theme File: ~/.config/copyq/themes/hornero-smart-colors.ini (auto-generated)
  • Cache: ~/.cache/dots/smart-colors/colors-copyq.ini (source file)

Automatic Generation

The CopyQ theme file (.ini format) is automatically generated when you:

  1. Change wallpapers via wpg
  2. Run dots-wal-reload
  3. Run dots-smart-colors --generate

The generated theme file is cached in ~/.cache/dots/smart-colors/colors-copyq.ini and symlinked to ~/.config/copyq/themes/hornero-smart-colors.ini.

Applying the Theme

To use the smart-colors theme in CopyQ:

  1. Via GUI: Open CopyQ → Preferences → Appearance → Select "hornero-smart-colors" from the theme dropdown
  2. Via Configuration: The theme will be available in CopyQ's appearance settings after generation

🔧 Customization

Modifying the Theme

To customize CopyQ's appearance:

  1. Regenerate the theme:

    dots-smart-colors --generate

  2. Edit the theme file (if needed):

    $EDITOR ~/.config/copyq/themes/hornero-smart-colors.ini

  3. Reload CopyQ:

    • Open CopyQ → Preferences → Appearance → Click "OK" to reload
    • Or restart CopyQ: copyq exit && copyq &

Available Theme Variables

The theme file uses these smart-colors placeholders:

  • bg - Primary background color
  • fg - Primary foreground/text color
  • alt_bg - Alternative background color
  • alt_fg - Alternative foreground color
  • sel_bg - Selection background color (uses accent color)
  • sel_fg - Selection foreground color
  • edit_bg, edit_fg - Editor colors
  • find_bg, find_fg - Search bar colors
  • notes_bg, notes_fg - Notes editor colors
  • num_fg - Number color

Customizing CSS Files

CopyQ uses CSS files from /usr/share/copyq/themes/ (or ~/.config/copyq/themes/ for overrides). The CSS files use placeholders like ${bg}, ${fg}, etc. that are defined in the .ini theme file.

To customize CSS:

  1. Copy the CSS file you want to modify:

    cp /usr/share/copyq/themes/items.css ~/.config/copyq/themes/

  2. Edit the CSS file (it will use placeholders from the theme .ini)

  3. Reload CopyQ to apply changes

🚀 Usage

Basic Commands

# Show CopyQ window
copyq show

# Hide CopyQ window
copyq hide

# Toggle visibility
copyq toggle

# Open context menu
copyq menu

# Exit CopyQ server
copyq exit

Integration with Dots Scripts

CopyQ is integrated with the dots-clipboard script:

# Launch clipboard manager (auto-detects CopyQ)
dots-clipboard

# Force CopyQ backend
dots-clipboard --backend=copyq

📋 Features

Visual Features

  • Theme-Adaptive Colors: Automatically matches your current theme
  • Rounded Corners: Modern 12px border-radius
  • Smooth Animations: 0.2s transitions for all interactive elements
  • Hover Effects: Visual feedback on hover
  • Focus Indicators: Clear focus states using accent color

Functional Features

  • Clipboard History: Stores up to 200 items (configurable)
  • Search: Filter items by text content
  • Tags: Organize items with tags
  • Pinned Items: Pin important items
  • Encryption: Encrypt sensitive clipboard items
  • Sync: Sync clipboard across devices

🔄 Automatic Updates

CopyQ's theme automatically updates when:

  1. Wallpaper Changes: Running wpg or changing wallpapers triggers dots-wal-reload
  2. Manual Reload: Running dots-wal-reload manually
  3. Smart Colors Regeneration: Running dots-smart-colors --generate

The CSS is regenerated from the template with current theme colors and symlinked to CopyQ's config directory.

🐛 Troubleshooting

Theme Not Applying

If CopyQ's theme doesn't update:

  1. Check theme file exists:

    ls -la ~/.config/copyq/themes/hornero-smart-colors.ini

  2. Regenerate theme:

    dots-smart-colors --generate

  3. Select theme in CopyQ:

    • Open CopyQ → Preferences → Appearance
    • Select "hornero-smart-colors" from theme dropdown
    • Click "OK" to apply

  4. Restart CopyQ (if needed):

    copyq exit
copyq &

Colors Not Matching Theme

If colors don't match your current theme:

  1. Regenerate smart colors:

    dots-smart-colors --generate

  2. Check theme file:

    cat ~/.cache/dots/smart-colors/colors-copyq.ini

  3. Reload theme in CopyQ:

    • Open Preferences → Appearance → Click "OK"

📚 Related Documentation

🎯 Design Alignment

CopyQ's theme aligns with HorneroConfig's design principles:

  • ✅ Theme-Adaptive: Colors adapt to any palette automatically
  • ✅ Modular: CSS template can be customized independently
  • ✅ Single Source of Truth: Colors come from smart-colors system
  • ✅ Graceful Degradation: Falls back to default Qt styling if CSS fails
  • ✅ Security by Default: No hardcoded secrets or sensitive data

📝 Notes

  • CopyQ uses a theme system with .ini files that define color placeholders
  • CSS files use placeholders like ${bg}, ${fg}, etc. that reference the theme .ini
  • The theme file is generated by dots-smart-colors --generate with current smart-colors
  • The generated theme is cached in ~/.cache/dots/smart-colors/ and symlinked to CopyQ's themes directory
  • CopyQ must reload the theme (via Preferences → Appearance → OK) or restart for changes to take effect
  • The theme file follows CopyQ's standard .ini format with placeholders for colors, fonts, and CSS customizations

💻 Kitty Terminal

🐱 Kitty Terminal Emulator Guide

Kitty is a modern, GPU-accelerated terminal emulator built for speed, flexibility, and customization. It’s ideal for developers, power users, and anyone who wants a fast, scriptable terminal experience.

[!TIP] Like everything in this setup, Kitty is fully customizable. You can tweak appearance, behavior, keybindings, and even integrate with your theme manager.

🚀 Why Use Kitty?

  • ⚡ GPU acceleration for smooth rendering
  • 🧩 Layouts and tab support
  • 🎨 Rich styling with font ligatures and emoji
  • 📜 Scriptable with shell commands
  • 📺 Inline graphics and image display support

⚙️ Configuration Basics

Kitty's configuration file is located at:

~/.config/kitty/kitty.conf

To edit it with chezmoi:

chezmoi edit ~/.config/kitty/kitty.conf
chezmoi apply

This file controls appearance, behavior, fonts, shortcuts, and more.

🎨 Installing and Applying Themes

Kitty supports full theme customization using its config system.

Using kitty-themes

We recommend using kitty-themes for easier management of community-curated themes.

Installation

git clone https://github.com/dexpota/kitty-themes ~/.config/kitty/themes

To list and apply a theme:

cd ~/.config/kitty/themes
./theme_launcher.sh  # Follow the prompts

This tool automatically updates your Kitty config with the selected theme.

🎨 Color Integration

Smart Colors & Pywal Integration

Your Kitty terminal automatically integrates with the smart colors system:

  • Automatic Updates: Colors refresh when you change wallpapers via wpg
  • Smart Adaptation: Colors are optimized for readability and theme consistency
  • Pywal Compatibility: Works seamlessly with existing pywal workflows

The terminal colors are automatically updated through the wal-reload script, ensuring perfect theme coordination across your entire desktop environment.

🧠 Tips for Customizing Kitty

  • Use Nerd Fonts or JetBrainsMono for ligatures and icon support
  • Bind shortcuts to control tabs or launch commands
  • Use background_opacity for transparency
  • Customize scrollback, padding, and cursor style

Example snippet:

font_family      Hack Nerd Font Mono
font_size        11
background_opacity 0.95
enable_audio_bell no

📦 Bonus: Integrate with Pywal

Use pywal to generate a dynamic color scheme based on your wallpaper, and source the kitty.conf colors dynamically.

wal -i path/to/wallpaper.jpg

Kitty will use the updated colors from your ~/.cache/wal/colors-kitty.conf file.

🆘 Need Help?

Kitty gives you the performance of a modern terminal with the aesthetic and control of a true power tool. Make it yours! 🐱💻

🐚 Zsh Shell

🌀 Zsh Configuration Guide

Zsh (Z Shell) is a powerful, interactive shell that offers advanced features, extensive customization, and a vibrant ecosystem of plugins and themes.

[!TIP] Everything in this setup is fully customizable. From themes, prompts, plugins, to aliases and functions — you’re in control. All configuration lives in your dotfiles and is managed through chezmoi.

⚙️ Configuration Files Location

Zsh is configured using a modular structure inside:

~/.zsh/config.d/

Every .zsh file inside this folder is automatically sourced on shell startup.

To edit files using chezmoi:

chezmoi edit ~/.zsh/config.d/yourfile.zsh --source ~/.dotfiles

Apply changes with:

chezmoi apply

[!TIP] Use separate files for aliases, plugins, and theme settings for better organization.

🔧 What You Can Customize

  • Prompt themes (e.g., Powerlevel10k)
  • Plugin managers (e.g., Antigen, Oh My Zsh)
  • Aliases and shell functions
  • Autocompletion and syntax highlighting
  • Environment variables

🎨 Prompt Themes

Powerlevel10k

To use Powerlevel10k:

  1. Install the theme
  2. Create a config file:
chezmoi edit ~/.zsh/config.d/p10k.zsh
source /usr/share/zsh-theme-powerlevel10k/powerlevel10k.zsh-theme
[ ! -f ~/.p10k.zsh ] || source ~/.p10k.zsh

Run p10k configure to customize your prompt interactively.

🔌 Plugin Managers

Antigen

Antigen allows you to load and manage plugins easily:

curl -L git.io/antigen > ~/.antigen.zsh
# ~/.zsh/config.d/antigen.zsh
source "$HOME/.antigen.zsh"
antigen apply

Oh My Zsh

Install with:

sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/main/tools/install.sh)"

Configure in:

# ~/.zsh/config.d/oh-my-zsh.zsh
export ZSH="/your/oh-my-zsh/path"
source "$ZSH/oh-my-zsh.sh"

📁 Structure and Recommendations

We recommend keeping your customizations modular:

  • aliases.zsh: command shortcuts
  • functions.zsh: reusable shell functions
  • theme.zsh: your theme settings
  • plugins.zsh: plugin manager logic

This keeps your configuration clean and easy to maintain.

🧪 Testing Changes

After editing your configuration:

source ~/.zshrc

Or simply open a new terminal tab/session.

[!TIP] Use zsh -x to debug issues during shell startup.

🆘 Need Help?

Zsh is not just a shell — it’s a productivity tool. Customize it to reflect your style and workflow! ⚡

📜 Dots Scripts Guide

Dots Scripts Utility Guide

dots is the unified entrypoint for Hornero scripts.

Usage

dots --help
dots --list
dots <script> [options]

Quickshell-first workflows

launcher

  • Primary: dots-quickshell ipc launcher toggle
  • Rescue path: minimal prompt
dots launcher
dots launcher --backend=quickshell

clipboard

  • Primary: dots-quickshell ipc utilities toggle
  • Secondary (Wayland): cliphist terminal picker
  • X11 fallback: copyq
  • Rescue path: minimal output
dots clipboard
dots clipboard --backend=copyq
dots clipboard --backend=cliphist

power-menu

  • Primary: dots-quickshell ipc session toggle
  • Fallback: minimal TUI selector
dots power-menu
dots power-menu --mode=quickshell
dots power-menu --mode=minimal

settings-gui

  • Quickshell control-center entrypoint
  • Starts Quickshell when needed, then toggles utilities
dots settings-gui

keyboard-help

  • Parses Hyprland keybindings dynamically
  • Viewer backend: terminal (less)
dots keyboard-help
dots keyboard-help --search=workspace

Theme and color workflows

appearance

  • Unified appearance API for Quickshell UI and scripts
  • Manages full themes/rices plus variant/mode/wallpaper syncing
dots appearance list
dots appearance current
dots appearance apply neon-city
dots appearance set-variant vibrant
dots appearance set-mode dark

smart-colors

  • Generates semantic colors and M3 scheme.json
  • Cache path: ~/.cache/dots/smart-colors/
dots smart-colors --generate --m3
dots smart-colors --concept=error

wal-reload

  • Rebuilds palette from wallpaper
  • Regenerates smart colors
  • Reloads Quickshell palette through IPC
dots wal-reload

wallpaper-set

  • Unified wallpaper entrypoint used by Quickshell and scripts
  • Delegates to wpg -s when available
  • Fallback path writes wallpaper state files and triggers smart-colors + Quickshell palette reload
dots wallpaper-set /path/to/wallpaper.jpg

Notes

  • Legacy Waybar/EWW/Rofi/JGMenu integration was intentionally removed.
  • dots rice remains available as legacy-compatible naming; dots appearance is the canonical contract.
  • dots-* scripts remain modular and can be called directly.

💾 Backup System

💾 Dots Backup Guide

The dots backup utility provides comprehensive backup and restoration capabilities for your dotfiles configuration. This tool helps you create snapshots, manage backup schedules, and restore previous configurations when needed.

[!TIP] Regular backups are essential for maintaining system stability and recovering from configuration issues. The backup tool integrates seamlessly with chezmoi and your dotfiles workflow.

🚀 Usage

# Create a backup with default settings
dots backup

# List all available backups
dots backup --list

# Restore from a specific backup
dots backup --rollback

# Set up automated backups with cron
dots backup --register-cron

# Remove automated backups
dots backup --unregister-cron

Advanced Options

# Custom backup location
dots backup --backup-dir=/path/to/custom/location

# Custom backup name
dots backup --backup-name=my-custom-backup

# Custom dotfiles directory (if not using default ~/.dotfiles)
dots backup --dotfiles-dir=/path/to/dotfiles

# Custom log file location
dots backup --log-file=/path/to/custom.log

📦 What Gets Backed Up

The backup tool creates comprehensive snapshots including:

  • Dotfiles source: Your complete ~/.dotfiles directory
  • Applied configurations: Key config files from ~/.config
  • Shell configurations: .zshrc, .bashrc, .profile, etc.
  • SSH configurations: ~/.ssh directory (with permission preservation)
  • Git configurations: .gitconfig and related files
  • Custom scripts: ~/.local/bin contents
  • Application data: Selected application configurations

🔄 Automated Backups

Setting Up Cron Jobs

# Register daily backups at 2 AM
dots backup --register-cron

# This creates a cron job that runs:
# 0 2 * * * /home/user/.local/bin/dots-backup --backup-name=daily_$(date +\%Y\%m\%d)

Managing Automated Backups

# View current cron jobs
crontab -l

# Remove automated backups
dots backup --unregister-cron

# Check backup logs
tail -f ~/.cache/dots/backup.log

🔧 Backup Management

Listing Backups

dots backup --list

This shows:

  • Backup name and date
  • Backup size
  • Location on disk
  • Backup integrity status

Restoring from Backup

# Interactive restoration (shows available backups)
dots backup --rollback

# The restore process:
# 1. Lists available backups with timestamps
# 2. Allows you to select which backup to restore
# 3. Creates a pre-restore backup of current state
# 4. Restores selected backup
# 5. Runs chezmoi apply to sync changes

📁 Backup Structure

Default backup location: ~/.dotfiles/backup/

backup/
├── dotfiles_backup_20250109_143022/
│   ├── dotfiles/          # Complete .dotfiles directory
│   ├── configs/           # Applied configurations
│   ├── ssh/              # SSH configurations (encrypted)
│   ├── scripts/          # Custom scripts
│   └── metadata.json     # Backup metadata and checksums
├── dotfiles_backup_20250108_140000/
└── ...

🛡️ Security Features

Permission Preservation

  • SSH keys maintain 600 permissions
  • Directories preserve 700/755 permissions
  • Sensitive files are properly secured

Encryption Support

# Backup with GPG encryption (if gpg is configured)
dots backup --encrypt

# Restore encrypted backup
dots backup --rollback --decrypt

Integrity Checking

  • SHA256 checksums for all backed up files
  • Automatic integrity verification during restore
  • Corruption detection and reporting

⚙️ Configuration

Default Settings

The backup tool uses these defaults:

  • Backup directory: ~/.dotfiles/backup
  • Backup name: dotfiles_backup_$(date)
  • Log file: /tmp/dots_backup_log_$(date).txt
  • Retention: Keeps last 10 backups by default

Customizing Backup Behavior

You can modify the backup script to:

  • Change default retention policy
  • Add/remove directories from backup scope
  • Modify backup naming conventions
  • Customize encryption settings
# Edit the backup script
chezmoi edit ~/.local/bin/executable_dots-backup
chezmoi apply

🆘 Troubleshooting

Common Issues

Permission Denied

# Ensure proper permissions for backup directory
chmod 755 ~/.dotfiles/backup

Large Backup Sizes

# Exclude large files or directories by editing the script
# Add exclusions for cache directories, logs, etc.

Failed Restores

# Check backup integrity
dots backup --verify backup_name

# Manual restoration
cp -r ~/.dotfiles/backup/backup_name/dotfiles ~/.dotfiles-restored

Recovery

If something goes wrong:

  1. Current config is automatically backed up before any restore
  2. Use chezmoi diff to see what changed
  3. Use chezmoi apply --dry-run to preview changes
  4. Restore from the automatic pre-restore backup if needed

💡 Best Practices

  1. Regular Backups: Set up daily automated backups
  2. Test Restores: Periodically test backup restoration
  3. Multiple Locations: Consider backing up to external storage
  4. Version Control: Use git for additional version tracking
  5. Documentation: Document any custom backup configurations

🔗 Related Commands

  • chezmoi archive - Create chezmoi-specific archives
  • dots config-manager - Manage configuration snapshots
  • dots security-audit - Audit backup security

The backup system works hand-in-hand with chezmoi to provide comprehensive configuration management and disaster recovery capabilities.

🚀 Eject System

🧨 Dots Eject Guide

While Chezmoi is a powerful and recommended tool for managing dotfiles across multiple systems, we understand that some users may prefer to maintain their own independent distribution.

[!TIP] This guide helps you eject from chezmoi and take full manual control of your dotfiles — useful for advanced users or custom workflows.

🚀 Why Use Chezmoi?

Chezmoi offers:

  • 🔁 Synchronization of dotfiles across machines
  • 🧼 Separation of source/config vs. applied state
  • 🔐 Secret management
  • 🔧 Easy templating and onboarding of new environments

But if you no longer wish to use chezmoi, you can safely eject.

📦 How to Eject from Chezmoi

Follow the official guide here: 👉 Migrate away from chezmoi

The process includes:

  1. Applying all changes to your home directory:

    chezmoi apply

  2. Copying the real files to a new git-tracked directory:

    mkdir ~/my-dotfiles
chezmoi managed --include=all | xargs -I {} cp --parents {} ~/my-dotfiles/
cd ~/my-dotfiles && git init

  3. Removing chezmoi from your workflow:

    sudo pacman -Rns chezmoi  # or appropriate command for your distro

Now you're managing your dotfiles fully manually or with your own tooling.

🧠 Things to Consider Before Ejecting

  • ✅ Are you managing secrets that chezmoi helps encrypt?
  • ✅ Do you still want templating, or are static files fine?
  • ✅ Do you want a clean separation between machine-specific and shared config?

If the answer is “no” or “you want full control,” ejecting is a valid next step.

🆘 Need Help?

Whether you stay with chezmoi or go fully manual, the goal is the same: dotfiles that reflect your ideal workflow. Choose the path that works best for you. 🛠️

🎵 Studio Setup

🎵 Studio — Audio Production Setup

This section covers the audio production stack installed by HorneroConfig, including DAW, guitar amp simulation, plugins, and Windows VST bridge support.

[!TIP] The full studio stack is installed automatically via chezmoi on Arch Linux. The install script lives at: home/.chezmoiscripts/linux/run_onchange_before_install-studio.sh.tmpl

📁 Managed Config Files

The following REAPER files are tracked by chezmoi under home/dot_config/REAPER/:

File Description
reaper-fxtags.ini FX plugin tags — user-curated organization of all plugins
ProjectTemplates/Basic Vocal Tracking - Linux Scarlett.RPP Project template for vocal recording with Scarlett interface

Everything else in ~/.config/REAPER/ (plugin scan caches, window positions, recent files, license info) is intentionally excluded — it is either machine-specific, auto-generated, or sensitive.

🔊 Audio Server — PipeWire

PipeWire is the foundation of the audio stack. It replaces PulseAudio and JACK while maintaining compatibility with both.

Installed packages

Package Role
pipewire Core audio/video server
pipewire-alsa ALSA compatibility layer
pipewire-pulse PulseAudio compatibility layer
pipewire-jack JACK compatibility layer (low-latency audio)
wireplumber Session/policy manager for PipeWire
pavucontrol GTK volume control GUI

Manual install

sudo pacman -S pipewire pipewire-alsa pipewire-pulse pipewire-jack wireplumber pavucontrol

Enable & start

systemctl --user enable --now pipewire pipewire-pulse wireplumber

[!NOTE] On a fresh install, chezmoi handles package installation but you may need to log out and back in for PipeWire to fully replace PulseAudio.

Verify PipeWire is active

After logging back in, confirm that PipeWire is serving as the PulseAudio backend:

pactl info

Look for this line in the output:

Server Name: PulseAudio (on PipeWire)

If you see PulseAudio (on PipeWire), everything is wired up correctly. Any other value (e.g., plain PulseAudio) means PipeWire is not active — check that pipewire-pulse is installed and wireplumber is running:

systemctl --user status pipewire pipewire-pulse wireplumber

🎛️ DAW — REAPER

REAPER is a professional, lightweight, and highly customizable Digital Audio Workstation.

Installed via

sudo pacman -S reaper

Notes

  • On Arch Linux, REAPER uses PipeWire-JACK for low-latency audio.
  • Configure the audio device under Options → Preferences → Audio → Device.
  • Set the device to JACK and start the session via PipeWire's JACK layer (no separate JACK daemon needed).

🎸 Guitar Amp Simulation — Guitarix

Guitarix is a virtual guitar amplifier running through the JACK audio system.

Installed packages

Package Role
guitarix Virtual guitar amp
gxplugins.lv2 Guitarix LV2 plugin set

Manual install

sudo pacman -S guitarix gxplugins.lv2

Usage

Guitarix connects to the JACK graph. With PipeWire-JACK active, simply launch:

guitarix

Use qpwgraph or helvum to visualize and patch audio connections in the PipeWire graph.

🔌 LV2 / Audio Plugins

A curated set of open-source LV2 plugins is installed for mixing, mastering, and effects.

Installed packages

Package Description
calf Studio-quality LV2 effects (EQ, reverb, compressor, chorus…)
lsp-plugins Linux Studio Plugins — professional mixing/mastering suite
lsp-plugins-docs Documentation for LSP Plugins
x42-plugins Collection of LV2 plugins by Robin Gareus (meters, MIDI tools…)

Manual install

sudo pacman -S calf lsp-plugins lsp-plugins-docs x42-plugins

🪟 Windows VST Bridge — yabridge + yabridgectl

yabridge lets you run Windows VST2/VST3 plugins natively in Linux via Wine.

Installed packages (AUR)

Package Role
yabridge Wine-based VST bridge
yabridgectl CLI tool to manage yabridge plugin installations

Manual install

yay -S yabridge yabridgectl

Basic setup

  1. Install Wine and your Windows VST plugins as usual.

  2. Add plugin directories to yabridgectl:

    yabridgectl add "$HOME/.wine/drive_c/Program Files/Steinberg/VstPlugins"

  3. Sync to generate bridge files:

    yabridgectl sync

  4. Verify the setup:

    yabridgectl status

[!TIP] Use yabridgectl sync --prune to remove bridges for plugins you've uninstalled.

References

📦 Full Package Summary

All packages installed by the studio chezmoi script:

# Audio server
sudo pacman -S pipewire pipewire-alsa pipewire-pulse pipewire-jack wireplumber pavucontrol

# DAW + Guitar amp + LV2 plugins
sudo pacman -S guitarix gxplugins.lv2 reaper calf lsp-plugins lsp-plugins-docs x42-plugins

# Windows VST bridge (AUR)
yay -S yabridge yabridgectl

🆘 Resources

🛡️ Security

🛡️ Security Guide

While these dotfiles are designed to provide a beautiful and personalized setup, privacy and security are just as important. This is an evolving journey — not a one-time setup — and we’re always open to suggestions.

[!TIP] You can tailor the security tools and settings to your preferences. All configurations can be automated or versioned using chezmoi where applicable.

🔒 Security Practices in Use

Here’s a list of tools and practices currently in place or under consideration:

✅ System Updates

  • Regular updates are essential.
  • I manually keep the system up-to-date using the package manager.
yay -Syyu  # [I use Arch, btw](https://wiki.archlinux.org/title/Arch_Linux)

[!TIP] Consider automating this process with a cron job or alias.

🛡️ Malware Scanning

  • ClamAV:
    • Run manual or scheduled scans
    • Keep virus database updated
sudo freshclam  # Update database
clamscan -r /home/youruser

🔥 Firewall

  • ufw: Simple firewall setup and management
sudo ufw enable
sudo ufw default deny incoming
sudo ufw allow out

🚫 IP Banning

  • fail2ban: Blocks IPs that show malicious behavior
sudo systemctl enable --now fail2ban

Check logs:

sudo fail2ban-client status

🔐 Password Management

If self-hosting or CLI usage is preferred, Bitwarden offers Bitwarden CLI.

🧬 Optional Hardening

  • Hardened Linux Kernel (optional):
    • A stricter kernel for additional protections
    • Great for advanced users but may break things unexpectedly

[!WARNING] Only recommended if you know your use cases won't be impacted.

🔎 Network & Port Scanning

  • nmap: Comprehensive network scanner
  • rustscan: Faster, modern alternative
sudo nmap -sS -p- 192.168.1.1
rustscan -a 192.168.1.1

Use for auditing your local network or spotting unknown open ports.

🔍 Automated Security Auditing

  • dots security-audit: Built-in comprehensive security audit tool
    • Scans applied configurations for exposed secrets
    • Checks file permissions across the system
    • Validates system security settings
    • Generates detailed security reports
# Run complete security audit
dots security-audit

# Run specific checks
dots security-audit --permissions  # Check file permissions only
dots security-audit --secrets      # Scan for exposed secrets only

# Apply automatic security fixes
dots security-audit --fix

# Generate detailed security report
dots security-audit --report

What it checks:

  • SSH key and config permissions
  • Credential file security
  • World-readable sensitive files
  • Applied configuration files for secrets
  • Environment variables and shell history
  • Firewall status and SSH configuration
  • Security tools (fail2ban, AppArmor/SELinux)
  • System integrity and updates

[!TIP] Run dots security-audit monthly or after major configuration changes to maintain good security hygiene.

🧪 Tips for Staying Secure

  • Use strong, unique passwords + 2FA where possible
  • Don’t run random scripts without reading them first
  • Use aliases to simplify safe commands (e.g., update-all)
  • Consider using a VPN and encrypted DNS (like DoH or DoT)
  • Keep regular backups in case of compromise

🆘 Need Help?

Security is an ongoing practice — start with the basics, stay informed, and evolve over time 🔐

🖥️ Hardware

Hardware Documentation

This section contains documentation related to hardware configuration and troubleshooting in your dotfiles setup.

Available Guides

Graphics

  • NVIDIA Troubleshooting Guide - Comprehensive guide for NVIDIA driver installation, configuration, and troubleshooting on Arch Linux.
  • Hybrid GPU Performance Guide - Performance optimization for laptops with Intel iGPU + NVIDIA dGPU, including Reverse PRIME configuration and power management.

Future Additions

This section will be expanded to include documentation for:

  • CPU and power management
  • Storage devices
  • Input devices
  • Audio devices
  • Network adapters
  • Other hardware components

Contributing

If you have experience with specific hardware configurations or troubleshooting steps, please consider contributing to this documentation. See the Contributing Guide for more information.

🎮 NVIDIA Troubleshooting

NVIDIA Troubleshooting Guide (Arch Linux)

This guide provides comprehensive troubleshooting steps for NVIDIA-related issues on Arch Linux, including driver installation, hybrid GPU setups, and solutions for common problems such as black screens or GPU conflicts.

Table of Contents

Driver Installation

Blacklisting Nouveau

The open-source nouveau driver can conflict with the proprietary NVIDIA driver. To disable it:

  1. Create a modprobe blacklist file:

    sudo nano /etc/modprobe.d/blacklist-nouveau.conf

  2. Add the following lines:

    blacklist nouveau
options nouveau modeset=0

  3. Regenerate the initramfs:

    sudo mkinitcpio -P

  4. Reboot:

    sudo reboot

Choosing Between nvidia and nvidia-dkms

Package Description Use When...
nvidia Precompiled for stock Arch kernel You're using the standard linux kernel
nvidia-dkms Builds driver per installed kernel (via DKMS) You're using linux-lts, zen, or custom kernels

Installation examples:

# For standard kernel
sudo pacman -S nvidia

# For DKMS version
sudo pacman -S nvidia-dkms

Common Issues

Black Screen After Login

  • Check NVIDIA modules:

    lsmod | grep nvidia

  • Check Xorg logs:

    cat /var/log/Xorg.0.log | grep nvidia

  • Confirm kernel parameters:

    cat /proc/cmdline

  • Ensure nvidia-drm.modeset=1 is passed:

    • For GRUB: edit /etc/default/grub and run sudo grub-mkconfig -o /boot/grub/grub.cfg
    • For systemd-boot with UKI: add --cmdline 'nvidia-drm.modeset=1' in your mkinitcpio.preset

Internal Display Not Detected (on Laptops)

  • Check current outputs:

    xrandr

  • Try enabling the internal panel:

    xrandr --output eDP-1 --auto

  • Open NVIDIA Settings GUI:

    nvidia-settings

[!TIP] This usually happens if the internal display is wired through the Intel iGPU and i915 was blacklisted.

GTK Apps Freezing or Blank

  • Check OpenGL status:

    glxinfo | grep "OpenGL renderer"

  • Ensure nvidia-utils and mesa are installed.

  • Configure Hyprland for optimal NVIDIA performance

No NVIDIA Processes Detected

  • Check:

    nvidia-smi
lsmod | grep nvidia
journalctl -b | grep -i nvidia

  • Ensure nvidia-persistenced is running if needed:

    systemctl status nvidia-persistenced

Diagnostic Commands

# Check which GPUs are present
lspci -k | grep -A 2 -E "(VGA|3D)"

# Verify modules
lsmod | grep -E 'nvidia|nouveau|i915'

# GPU renderer info
glxinfo | grep "OpenGL renderer"

# Display detection
xrandr

# NVIDIA status
nvidia-smi
nvidia-settings

# Kernel log
journalctl -b | grep -i nvidia

Hybrid GPU Setup (Intel + NVIDIA)

If your laptop uses both an integrated Intel GPU and a dedicated NVIDIA GPU:

  1. Install required packages:

    sudo pacman -S nvidia nvidia-utils nvidia-settings xf86-video-intel mesa

  2. Create /etc/modprobe.d/nvidia.conf:

    options nvidia-drm modeset=1

  3. For GRUB: edit /etc/default/grub:

    GRUB_CMDLINE_LINUX_DEFAULT="quiet nvidia-drm.modeset=1"
sudo grub-mkconfig -o /boot/grub/grub.cfg

  4. For systemd-boot with UKI:

    • Add --cmdline 'nvidia-drm.modeset=1' to your preset in /etc/mkinitcpio.d/linux.preset

    • Then regenerate:

      sudo mkinitcpio -p linux

  5. Optional Xorg config:

    sudo nano /etc/X11/xorg.conf.d/10-hybrid.conf
    Section "Device"
    Identifier "Intel Graphics"
    Driver "modesetting"
    BusID "PCI:0:2:0"
    Option "TearFree" "true"
EndSection

Section "Device"
    Identifier "NVIDIA"
    Driver "nvidia"
    BusID "PCI:1:0:0"
    Option "AllowEmptyInitialConfiguration"
EndSection

Quick Recovery Checklist

If you're stuck on a black screen or SDDM doesn't appear:

# Switch to TTY
Ctrl + Alt + F2

# Check for blacklisted Intel
ls /etc/modprobe.d/

# Remove i915 blacklist if present
sudo rm /etc/modprobe.d/blacklist-intel.conf

# Rebuild initramfs
sudo mkinitcpio -P

# Reboot
sudo reboot

Additional Resources

⚡ Hybrid GPU Performance

Hybrid GPU Performance Guide

Hardware Setup

  • iGPU: Intel Raptor Lake-S UHD Graphics
  • dGPU: NVIDIA RTX 4060 Max-Q Mobile
  • Physical Connection:
    • Laptop Display (eDP-1) → Intel iGPU
    • External Monitor (HDMI-A-5) → NVIDIA dGPU (physical HDMI port)

The Performance Problem

When your external monitor is connected directly to the NVIDIA HDMI port, it creates a Reverse PRIME situation:

┌──────────────────────────────────────────────────────┐
│                                                      │
│  Intel iGPU (renders everything)                    │
│         │                                            │
│         ├──► eDP-1 (laptop) ✓ Direct                │
│         │                                            │
│         └──► [Frame Copy] ──► NVIDIA dGPU           │
│                                    │                 │
│                                    └──► HDMI-A-5     │
│                                         (external)   │
│                                                      │
│  Overhead: ~5-15ms latency per frame copy           │
└──────────────────────────────────────────────────────┘

Impacts

  • ❌ Additional latency: 5-15ms per frame copy
  • ❌ NVIDIA always active: Doesn't enter deep power-save
  • ❌ Higher power consumption: ~5-10W extra even without gaming
  • ⚠️ Possible tearing: If VRR isn't properly configured

Solutions and Trade-offs

✅ Option 1: Keep Reverse PRIME (Current Configuration)

Advantages:

  • Better battery life than NVIDIA full-time
  • Wayland works better with Intel as compositor
  • NVIDIA available for gaming with prime-run

Disadvantages:

  • Frame copies Intel→NVIDIA
  • ~5-15ms latency on external monitor
  • NVIDIA never completely turns off

When to use:

  • Working primarily on battery
  • Not gaming on external monitor
  • Prioritize efficiency over minimal latency

⚡ Option 2: NVIDIA as Primary GPU

Change to have NVIDIA render everything (including compositor).

Required configuration:

# In environment.conf, change to:
env = LIBVA_DRIVER_NAME,nvidia
env = GBM_BACKEND,nvidia-drm
env = __GLX_VENDOR_LIBRARY_NAME,nvidia
env = WLR_NO_HARDWARE_CURSORS,1

# Remove:
# env = __NV_PRIME_RENDER_OFFLOAD,1

Advantages:

  • No frame copies for external monitor
  • Minimal latency on HDMI-A-5
  • Better for fulltime gaming

Disadvantages:

  • ❌ MUCH higher consumption (+15-25W even at idle)
  • ❌ Fans always active under Wayland
  • ❌ Worse Wayland support on NVIDIA
  • ❌ Battery drains 2-3x faster

When to use:

  • External monitor always connected
  • Intensive gaming on external monitor
  • Laptop always plugged into power

🎯 Option 3: Dynamic Hybrid Mode (Recommended)

Use different profiles depending on usage:

For Work/Battery (Current config)

# Already configured - uses Intel for compositor
hyprctl reload

For Gaming/Performance

# Script to temporarily switch to NVIDIA primary
prime-run hyprland  # Or configure separate Hyprland session

Current Applied Configuration

Your system is configured for Option 1 (Optimized Reverse PRIME):

environment.conf

  • Intel handles VA-API (video decode)
  • NVIDIA configured to present on physical HDMI port
  • __NV_PRIME_RENDER_OFFLOAD variables active
  • Hardware cursors enabled (test for glitches)

monitors.conf

  • eDP-1 explicitly configured
  • HDMI-A-5 with auto-detect
  • Reverse PRIME flow documented

Verifying Performance

1. Check which GPU Hyprland uses

# See active GPU for Hyprland
hyprctl systeminfo | grep -i "gpu"

# Or verify processes:
nvidia-smi  # Check if Hyprland appears here

2. Check input latency

# On external monitor, move windows quickly
# Feel if there's noticeable lag vs laptop screen

3. Measure power consumption

# See power consumption
cat /sys/class/power_supply/BAT*/power_now
# Lower number = better (values in µW)

# See NVIDIA GPU usage
nvidia-smi dmon

4. If you see cursor glitches on external monitor

# Uncomment in environment.conf:
env = WLR_NO_HARDWARE_CURSORS,1

Recommendations

For your case (2 monitors, hybrid laptop)

  1. Keep current configuration (Reverse PRIME) for daily use
  2. Monitor latency on external monitor
  3. If you notice annoying lag: Consider switching to NVIDIA primary
  4. For gaming: Use prime-run or launch games with NVIDIA variables

Signs you should switch to NVIDIA primary

  • ✓ Noticeable lag/tearing on external monitor
  • ✓ Frequently gaming on external monitor
  • ✓ Laptop always plugged into power
  • ✓ Don't care about fan noise

Keep Reverse PRIME if

  • ✓ Regularly use battery
  • ✓ Current lag is imperceptible
  • ✓ Prioritize silence/low temperature
  • ✓ Not doing intensive gaming

Troubleshooting

Problem: External monitor has noticeable lag

Solution: Switch to NVIDIA primary (Option 2)

Problem: Cursor corrupts on external monitor

Solution: Enable WLR_NO_HARDWARE_CURSORS,1

Problem: NVIDIA doesn't release memory

Solution:

# Kill persistent NVIDIA processes
sudo systemctl restart display-manager

Problem: Tearing on external monitor

Solution:

# In hyprland.conf, verify:
misc {
    vrr = 1  # Variable Refresh Rate
    no_direct_scanout = false
}

Useful Commands

# See active GPUs
lspci | grep -E "VGA|3D"

# See processes using NVIDIA
nvidia-smi

# See monitors in Hyprland
hyprctl monitors

# See DRM outputs
drm_info | grep -A5 "Connector"

# See which GPU a specific window uses
hyprctl clients | grep -A10 "class:"

# Launch specific app on NVIDIA
prime-run <app>
__NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia <app>

Performance States Explained

NVIDIA GPUs have different performance states (P-states):

P-State Mode Power Usage Use Case
P0 Maximum Performance ~50-55W Gaming, Heavy Compute
P2 Balanced ~20-30W Video Editing
P5 Low Power ~5-10W Display Output Only
P8 Idle (not achievable with display) ~1-2W No display connected

In Reverse PRIME mode with external monitor, NVIDIA stays at P5 (5W) minimum.

Expected Performance Metrics

Battery Life Impact

  • Before optimization: ~15-25W additional GPU consumption
  • After (Reverse PRIME): ~5W (3-5x better battery duration)
  • NVIDIA Primary: ~20-30W (worst battery life)

Latency

  • Laptop Monitor (eDP-1): 0ms overhead ✓
  • External Monitor (HDMI-A-5): ~5-10ms overhead (frame copy)

Gaming

Use prime-run to force full NVIDIA:

prime-run steam
prime-run lutris
prime-run godot

Advanced: Creating Profile Scripts

Create profile switching scripts for different scenarios:

~/.local/bin/dots-gpu-mode-battery

#!/usr/bin/env bash
# Switch to battery-optimized mode (Intel primary)

# Copy environment.conf with Intel settings
# Reload Hyprland
hyprctl reload
notify-send "GPU Mode" "Switched to Battery Mode (Intel primary)"

~/.local/bin/dots-gpu-mode-performance

#!/usr/bin/env bash
# Switch to performance mode (NVIDIA primary)

# Copy environment.conf with NVIDIA settings
# Reload Hyprland
hyprctl reload
notify-send "GPU Mode" "Switched to Performance Mode (NVIDIA primary)"

References

📶 Network Manager

🌐 Network Manager Guide

This section provides guidance for managing and configuring your network setup using NetworkManager, with custom dotfiles support.

[!TIP] Like everything else in this setup, the Network Manager integration is fully customizable. You can configure connections, UI tools, and even define shortcuts or scripts — all managed through your dotfiles and chezmoi.

⚙️ Tools You Can Use

Depending on your preference, you can use either graphical or terminal-based tools for managing networks:

1. nmtui – TUI interface (Text-based User Interface)

nmtui

Use this for:

  • Activating or deactivating connections
  • Connecting to Wi-Fi
  • Setting static IP addresses

2. nmcli – Command-line Interface

nmcli device wifi list
nmcli device wifi connect <SSID> password <password>

Use this for scripting, automating, or managing networks programmatically.

3. network-manager-applet – GUI tray icon

If you're running a system tray (e.g., via Waybar), you can use the applet to manage Wi-Fi and VPNs.

Install:

sudo pacman -S network-manager-applet  # Arch-based

📁 Dotfiles Integration

While network configurations aren't typically stored directly in the dotfiles, you can:

  • Create helper scripts to automate Wi-Fi/VPN switching
  • Manage your tray applet visibility and behavior
  • Bind hotkeys for toggling Wi-Fi, VPN, or Airplane Mode

You can version any helper script or autostart command using chezmoi:

chezmoi edit ~/.config/autostart/network-helper.sh

✨ Example: Quick Connect Script

Here’s an example nmcli script that you can store in ~/.local/bin/connect-home-wifi.sh:

#!/bin/bash
nmcli device wifi connect "HomeWiFi" password "yourpassword"

Make it executable:

chmod +x ~/.local/bin/connect-home-wifi.sh

Add it to your chezmoi config or call it from a keybinding.

🧪 Debugging Network Issues

Useful nmcli commands:

nmcli general status
nmcli device
nmcli connection show
journalctl -u NetworkManager.service

🆘 Need Help?

Take control of your network configuration with tools that match your workflow — whether it's terminal, GUI, or automation! 📡

🤝 Contributing

Thank you for considering contributing to Dotfiles! We appreciate your interest in improving the project. To ensure a smooth and collaborative contribution process, please review the following guidelines.

Communication

Before making any changes or submitting a pull request, we recommend discussing your proposed changes with the repository owners. This can be done through creating an issue, sending an email, or any other method of communication that suits you. Engaging in a discussion beforehand helps ensure that your contributions align with the project's goals and guidelines.

Please note that Dotfiles has a Code of Conduct that we expect all contributors to adhere to. Kindly follow the code of conduct in all your interactions within the project community.

Ways to Contribute

You can contribute to Dotfiles in various ways, including:

Pull Requests

To contribute through a pull request, please follow these steps:

  1. Fork the Dotfiles repository to your own GitHub account.
  2. Create a new branch for each feature or improvement you plan to work on.
  3. Submit a pull request from each feature branch to the main branch of the main repository.

It's essential to separate new features or improvements into separate feature branches and submit a pull request for each branch. This allows us to review and merge new contributions individually, ensuring better visibility and management of changes.

Code Guidelines

When writing code for Dotfiles, please adhere to the following guidelines:

  • Follow shell scripting best practices, such as those outlined in Google's Shell Style Guide.
  • Aim for POSIX compliance to ensure compatibility across different environments.
  • Use double quotes around variables ("${variable}") instead of bare variables ($variable).
  • Use UPPER_CASE for constants and global variables, and lower_case for other variables.
  • Utilize single square brackets ([ condition ]) for conditionals, such as in 'if' statements.
  • Write clean and readable code, emphasizing clarity and maintainability.
  • Add comments where necessary, especially to explain complex functions or provide context.
  • Clearly document the arguments that a function accepts (if any).
  • Use different error codes when exiting a script and provide explanations for them at the top of the file.
  • Include a copyright disclaimer below the shebang line and any other relevant copyright notices when creating new files or making significant changes.
  • Limit lines to a maximum of 80 characters for improved readability.
  • Name setup scripts as setup-<function> without file extensions.
  • Use the .sh extension for libraries and exclude the shebang line.
  • Scripts and libraries should not be executable, as permissions will be set during compilation.
  • Validate your code using a shell linter, such as shellcheck.
  • Test your code before submitting a pull request (unless it's a draft).
  • Provide detailed and informative commit messages that accurately describe the changes made.

Thank you for considering these guidelines when contributing to Dotfiles. Your efforts contribute to the project's quality and overall success. Happy coding!

🧪 Testing

🧪 Dotfiles Testing Environment Guide

Whether you're looking to contribute to the Dotfiles project or simply want to preview how everything looks before applying it to your system — we've got you covered with dedicated testing environments.

[!TIP] The testing setup allows you to experiment safely without affecting your real configuration. It’s a perfect playground for customizing themes, scripts, and behaviors.

🚀 Why Use the Testing Environment?

  • 🧰 Preview your desktop layout and tool behavior
  • 🔧 Tweak configs and see changes instantly
  • 🤝 Contribute improvements with confidence
  • 🧼 Avoid breaking your daily setup during experimentation

📖 How to Get Started

To learn how to set up the test environments, check out the official Testing Docs.

These docs include:

  • Environment requirements
  • Setup steps (VM or container)
  • How to apply dotfiles without affecting your main system

🔁 What Can You Test?

You can try out:

  • 🪟 Window manager (Hyprland)
  • 🎨 Themes (Rofi, Waybar, Zsh prompt)
  • 🧩 Modules and utilities
  • 🧪 Custom scripts or aliases
  • 🛡️ Security configurations and defaults

🔄 Use this environment as a sandbox — test safely and iterate freely.

🧠 Tips for Effective Testing

  • Use a virtual machine or container for complete isolation
  • Snapshot your test environment before big changes
  • Commit working test configs to a feature branch before merging
  • Use chezmoi apply --dry-run to simulate changes before applying

🆘 Need Help?

Contributing or customizing just got easier. Jump into the testing environment, play around, and see how everything fits your workflow — worry-free!

Happy testing 🧪🎉

📅 Changelog 2025

📅 Changelog 2025

This page documents all major improvements, new features, and updates to the HorneroConfig dotfiles framework throughout 2025.

🎉 January 2025 - Smart Colors Revolution & UI Optimization

🧠 Smart Colors System 2.0

🆕 Theme-Adaptive Color Intelligence

The biggest update to the smart colors system since its inception! The system now automatically detects whether your theme is light or dark and adapts ALL colors accordingly.

New Features:

  • Automatic Theme Detection: Uses background luminance to determine light (>128/255) vs dark themes
  • Dual-Mode Color Optimization: Different color sets for light and dark themes
  • Enhanced Contrast: Optimized readability for both theme types

Color Adaptation Examples:

# Dark Theme (background: #011936)
info: #00dddd    # Bright cyan for better contrast
success: #55dd55  # Bright green for visibility
warning: #ffaa00  # Bright orange for attention

# Light Theme (background: #f0f0f0)
info: #0066cc    # Deep blue for readability
success: #008800  # Dark green for comfort
warning: #cc6600  # Dark orange for subtlety

🆕 Four New Smart Concepts

Added background and foreground variants for better UI consistency:

  • background: Primary background color
  • background-alt: Secondary/accent background (usually color1)
  • foreground: Primary text color (theme-optimized)
  • foreground-alt: Secondary text color (usually color5)

Usage:

# Get new concepts
dots-smart-colors --concept=background-alt
dots-smart-colors --concept=foreground-alt

# All available in generated files
~/.cache/dots/smart-colors/colors.sh
~/.cache/dots/smart-colors/colors-waybar.css

🎨 Enhanced Visualization

Updated --analyze and --colors commands now show the new concepts:

dots-smart-colors --analyze --colors

New Output Sections:

  • Smart Background & Foreground (4 new concepts)
  • Smart Semantic Colors (theme-adaptive)
  • Smart Basic Colors (theme-adaptive)
# Smart floating script integration
```conf

Hyprland Floating Window Configuration:

# Hyprland floating window rules are configured in hyprland.conf
# Global floating window constraints
floating_minimum_size 400 x 300
floating_maximum_size 1400 x 900

📏 Intelligent Sizing Algorithm

# Automatically calculates optimal dimensions
width = screen_width × 70%
height = screen_height × 65%

# Examples:
1920×1080 → 1344×702 floating window
2560×1440 → 1400×900 (limited by max constraint)
1366×768  → 956×499 floating window

Use Cases:

  • Calculator applications
  • Quick terminal sessions
  • Note-taking overlays
  • Media player controls
  • System utility dialogs

🔧 Technical Improvements

🗂️ Enhanced File Generation

All smart color files now include the new background/foreground variants:

Updated Files:

  • ~/.cache/dots/smart-colors/colors.sh - Shell variables
  • ~/.cache/dots/smart-colors/colors.env - Environment exports
  • ~/.cache/dots/smart-colors/colors-polybar.conf - Polybar integration
  • ~/.cache/dots/smart-colors/colors-eww.scss - EWW widgets
  • ~/.cache/dots/smart-colors/colors-i3.conf - i3 window manager

📖 Documentation Updates

New Wiki Pages:

Updated Wiki Pages:

🎯 Workflow Improvements

Better Developer Experience:

  • More intuitive color usage across all applications
  • Consistent visual hierarchy
  • Reduced cognitive load from visual noise
  • Better accessibility through improved contrast

Enhanced User Experience:

  • Smarter window management with automatic sizing
  • Perfect floating window positioning
  • Theme-adaptive colors for any wallpaper
  • Seamless integration across all components

🚀 Impact & Benefits

👁️ Visual Improvements

  • 50% reduction in aggressive accent color usage
  • Better readability across light and dark themes
  • Consistent hierarchy throughout the interface
  • Reduced eye strain from optimized color choices

⚡ Productivity Gains

  • Faster floating window workflow with smart sizing
  • Automatic adaptation to different screen sizes
  • Less manual positioning required for floating windows
  • Seamless theme switching with adaptive colors

🛠️ Technical Benefits

  • Universal compatibility with any color scheme
  • Automatic optimization without manual configuration
  • Centralized color management across all applications
  • Future-proof architecture for new features

🔮 Looking Forward

🎯 Planned Features

Smart Colors System:

  • Application-specific color profiles
  • Custom theme detection algorithms
  • Advanced contrast ratio optimization
  • Integration with more applications

Window Management:

  • Saved window positions per application
  • Smart tiling return with memory
  • Gesture-based window controls
  • Animation transitions between states

Overall Framework:

  • Enhanced rice theme switching
  • Better multi-monitor support
  • Performance optimizations
  • Extended customization options

This changelog represents the continuous evolution of HorneroConfig, focusing on intelligent automation, visual excellence, and enhanced user experience. Each update builds upon the hornero bird philosophy: creating robust, functional, and beautiful environments. 🏠✨

🏠 Home

🏠 HorneroConfig - Comprehensive Dotfiles Framework

Docs | Changelog | Contributing

You might be here looking for (Linux) rice reference or to (full?) replicate my personal configuration of my favorite Window Managers and several apps as well. ⛄

HorneroConfig is your artisanal toolkit for crafting the perfect digital workspace. Named after the industrious hornero bird, renowned for its skillful nest-building, our framework empowers you to construct a robust, functional, and personalized computing environment.

Perfectly suited for a wide array of Desktop Environments and Window Managers, HorneroConfig thrives across different platforms including GitHub Codespaces, Gitpod, VS Code Remote - Containers, or even Linux distributions that are not Arch Linux.

Backed by the versatile Chezmoi, HorneroConfig stands out as a dotfiles manager that adapts flexibly to your needs, streamlining machine setup and ensuring consistency across devices. Embrace the spirit of the hornero, and let HorneroConfig transform your configurations into a harmonious blend of elegance and efficiency.

✨ Key Features

  • 🎨 Advanced Rice System: Switch between beautiful desktop themes instantly
  • 🧠 Smart Colors: Intelligent color adaptation for optimal readability and theme consistency
  • 🐚 Quickshell: Unified QML desktop shell (bar, launcher, dashboard, notifications, AI chat)
  • 🎨 Material Design 3: Intelligent color theming from wallpaper analysis
  • 🌊 Hyprland: Dynamic tiling Wayland compositor with smooth animations
  • 📦 Easy Management: Simple installation and configuration via chezmoi
  • 🔧 100+ Scripts: Comprehensive automation and utility scripts
  • 🔄 Automatic Theming: Seamless wallpaper-to-theme integration
  • 🛡️ Security: Built-in security auditing and hardening tools

Most were written from scratch. Core stack:

  • Compositor 🌊 Hyprland - Dynamic tiling Wayland compositor
  • Desktop Shell 🐚 Quickshell - Unified QML shell (bar, launcher, notifications, dashboard)
  • Launcher Fallback 🚀 terminal prompt - lightweight rescue launcher
  • Notifications 🔔 Built into Quickshell (replaces Mako)
  • Terminal Emulator 🐾 Kitty - GPU-accelerated terminal
  • Shell 🐚 Zsh with Powerlevel10k prompt
  • Lockscreen 🔒 Hyprlock - Secure lock screen
  • Wallpaper 🖼️ Quickshell + wpgtk integration via dots-wallpaper-set
  • File Manager 🃏 Thunar with customized side pane
  • and many more!

🚀 Installation & Performance

Chaotic-AUR Repository

HorneroConfig automatically configures the Chaotic-AUR repository during installation. This provides:

  • ⚡ Precompiled Binaries: Skip building AUR packages from source
  • 🎯 Faster Setup: Reduce installation time by 50-70%
  • 🔄 Regular Updates: Automatically maintained packages
  • 📦 Popular Packages: Hyprland + Quickshell ecosystem, pamac-aur, auto-cpufreq, and more

The repository is configured automatically by the chezmoi script at:

home/.chezmoiscripts/linux/run_onchange_before_install-000-chaotic-aur.sh.tmpl

For more information, visit the Chaotic-AUR documentation.

📜 Dots Scripts

Dots Scripts Utility Guide

dots is the unified entrypoint for Hornero scripts.

Usage

dots --help
dots --list
dots <script> [options]

Quickshell-first workflows

launcher

  • Primary: dots-quickshell ipc launcher toggle
  • Rescue path: minimal prompt
dots launcher
dots launcher --backend=quickshell

clipboard

  • Primary: dots-quickshell ipc utilities toggle
  • Secondary (Wayland): cliphist terminal picker
  • X11 fallback: copyq
  • Rescue path: minimal output
dots clipboard
dots clipboard --backend=copyq
dots clipboard --backend=cliphist

power-menu

  • Primary: dots-quickshell ipc session toggle
  • Fallback: minimal TUI selector
dots power-menu
dots power-menu --mode=quickshell
dots power-menu --mode=minimal

settings-gui

  • Quickshell control-center entrypoint
  • Starts Quickshell when needed, then toggles utilities
dots settings-gui

keyboard-help

  • Parses Hyprland keybindings dynamically
  • Viewer backend: terminal (less)
dots keyboard-help
dots keyboard-help --search=workspace

Theme and color workflows

appearance

  • Unified appearance API for Quickshell UI and scripts
  • Manages full themes/rices plus variant/mode/wallpaper syncing
dots appearance list
dots appearance current
dots appearance apply neon-city
dots appearance set-variant vibrant
dots appearance set-mode dark

smart-colors

  • Generates semantic colors and M3 scheme.json
  • Cache path: ~/.cache/dots/smart-colors/
dots smart-colors --generate --m3
dots smart-colors --concept=error

wal-reload

  • Rebuilds palette from wallpaper
  • Regenerates smart colors
  • Reloads Quickshell palette through IPC
dots wal-reload

wallpaper-set

  • Unified wallpaper entrypoint used by Quickshell and scripts
  • Delegates to wpg -s when available
  • Fallback path writes wallpaper state files and triggers smart-colors + Quickshell palette reload
dots wallpaper-set /path/to/wallpaper.jpg

Notes

  • Legacy Waybar/EWW/Rofi/JGMenu integration was intentionally removed.
  • dots rice remains available as legacy-compatible naming; dots appearance is the canonical contract.
  • dots-* scripts remain modular and can be called directly.

🎨 Rice System

Rice System: Theme Management

The rice system is now managed through the Quickshell-first appearance workflow.

Canonical Commands

dots appearance list
dots appearance current
dots appearance apply neon-city
dots appearance set-variant vibrant
dots appearance set-mode dark
dots appearance set-wallpaper /path/to/wallpaper.jpg

dots rice ... is retained as compatibility naming, but dots appearance ... is the canonical interface.

What a Rice Controls

  • wallpaper selection
  • smart-colors / M3 palette generation
  • light/dark mode and M3 variant
  • GTK theme metadata and optional extras
  • Quickshell-facing appearance state

Quickshell Integration

Appearance changes done from the control center can be previewed first, then committed with Apply/Save.

flowchart LR
  user[UserSelectsAppearance] --> preview[QuickshellPreview]
  preview --> apply[ApplyOrSave]
  apply --> cli[dots-appearanceApply]
  cli --> palette[dots-smart-colorsAndScheme]
  palette --> shell[QuickshellReload]

Structure

Rices live under:

~/.local/share/dots/rices/<rice-name>/

Typical files:

  • config.sh
  • executable_apply.sh
  • backgrounds/
  • optional preview.*

Notes

  • Legacy Rofi/JGMenu theme selectors were removed from the maintained path.
  • The maintained desktop path is Hyprland + Quickshell.

🧠 Smart Colors

Smart Colors System

Smart Colors generates semantic colors and Material Design 3 palettes from the current wallpaper, then keeps Quickshell synchronized.

Primary Contract

  • Quickshell is the main consumer through ~/.cache/dots/smart-colors/scheme.json.
  • dots-wal-reload and dots-wallpaper-set trigger palette refresh and Quickshell IPC reload.
  • Script consumers can source shell/env exports from the same cache directory.

Wallpaper Pipeline Contract

Historical pipelines

  • wpgtk pipeline: wpg -s <image> -> wpg.conf runs dots-wal-reload and refreshes shell colors.
  • Legacy Quickshell direct pipeline: UI actions used to call compositor-specific wallpaper setters directly, bypassing wpg and global reload orchestration.

The direct pipeline could desynchronize ~/.config/wpg/.current from shell/runtime state and miss some app reloads that are centralized in dots-wal-reload.

Unified contract

  • Use dots-wallpaper-set as the single entrypoint for wallpaper changes from shell UI/actions.
  • When wpg is available, dots-wallpaper-set delegates to wpg -s so wpgtk remains source-compatible.
  • Wallpaper resolution priority is unified across scripts:
    1. Explicit argument
    2. ~/.local/state/dots/wallpaper/path (canonical persistent pointer; respects DOTS_STATE_DIR / XDG_STATE_HOME)
    3. ~/.cache/wal/wal (pywal)
    4. ~/.config/wpg/.current (optional, when using wpgtk)

Main Commands

dots-smart-colors --generate --m3
dots-smart-colors --analyze
dots-smart-colors --concept=error
dots-wal-reload

Generated Cache

All generated files are written to ~/.cache/dots/smart-colors/.

Core files:

  • scheme.json (Quickshell M3 palette)
  • colors.sh (shell variables for scripts)
  • colors.env (export-friendly environment file)
  • colors-hyprlock.env (lockscreen integration)
  • colors-kitty.conf (terminal integration)
  • colors.css (generic CSS variables)

Compatibility files may exist for external tooling, but they are not part of the primary UX contract.

Data Flow

flowchart LR
  wallpaper[WallpaperChange] --> set[dots-wallpaper-set]
  set --> wal[dots-wal-reload]
  wal --> smart[dots-smart-colorsGenerate]
  smart --> scheme[schemeJson]
  scheme --> colours[QuickshellColoursService]
  colours --> ui[QuickshellUIUpdated]

Troubleshooting

# Rebuild smart-colors cache
dots-smart-colors --generate --m3

# Confirm cache files exist
ls -la ~/.cache/dots/smart-colors/

# Force shell-side reload path
dots-quickshell ipc colours reload

Notes

  • Legacy Waybar/EWW/Rofi integrations are no longer part of the maintained path.
  • The supported default stack is Hyprland + Quickshell.