NixOS Hyprland Desktop Module Assistant

Expert assistant for developing and maintaining the Kartoza NixOS Hyprland desktop environment. This skill helps you work with NixOS flakes, Wayland compositor configurations, modular dotfiles, and integrated desktop utilities.

What This Skill Does

Assists with development of a standalone NixOS flake that provides a complete Hyprland desktop environment with Kartoza branding. The flake exports a NixOS module that can be imported into any NixOS system configuration.

Key Capabilities

Instructions

1. Understanding the Architecture

Before making any changes:

2. Development Workflow

Always follow this sequence:

```bash

Enter development environment

nix develop

Format Nix files before committing

nix fmt

Validate flake and formatting

nix flake check

CRITICAL: Validate Hyprland config after any changes

hyprland --verify-config --config dotfiles/hypr/hyprland.conf

```

3. Working with Waybar Modular Configuration

The waybar uses a unique modular system - never edit `config` directly:

**File Organization**:

**Making Changes**:

```bash

cd dotfiles/waybar

Edit individual module files

vim config.d/10-wlr-workspaces.json

Rebuild merged config

./build-config.sh

Test with live reload

waybar -c config -s style.css --log-level debug

```

**Adding New Widget**:

1. Create `config.d/90-custom-mywidget.json`

2. Use return-type "json" for dynamic widgets

3. Run `build-config.sh` to regenerate config

4. Restart waybar to test

4. Swaync Layer Configuration

**CRITICAL CONSTRAINT**: The swaync `config.json` must use `"layer": "top"` (not `"overlay"`).

**Reason**: The overlay layer creates an invisible input-capturing region that blocks mouse clicks on window title bar buttons in the upper-right corner of the screen. The top layer properly handles input passthrough when closed.

When modifying notification settings, always preserve this layer configuration.

5. Keyboard Layout Management

The module provides intelligent keyboard layout switching:

**Configuration Pattern**:

```nix

kartoza.hyprland-desktop = {

enable = true;

keyboardLayouts = [ "us" "de" "fr" ]; # Customize layouts

};

```

**Implementation Details**:

6. Wallpaper Configuration

Unified wallpaper system for desktop and lock screen:

**Configuration Pattern**:

```nix

kartoza.hyprland-desktop = {

enable = true;

wallpaper = "/path/to/custom-wallpaper.jpg"; # Override default

};

```

**Default**: `/etc/wallpapers/kartoza.png`

**Used By**: swww (desktop background), swaylock (lock screen)

7. User Configuration Override System

Follow XDG Base Directory Specification:

**Override Process**:

```bash

System configs (provided by module)

/etc/xdg/hypr/hyprland.conf

/etc/xdg/waybar/config

/etc/xdg/swaync/config.json

User overrides (take precedence)

~/.config/hypr/hyprland.conf

~/.config/waybar/config

~/.config/swaync/config.json

Copy system config to customize

cp /etc/xdg/hypr/hyprland.conf ~/.config/hypr/

```

**Script PATH Resolution**:

8. Workspace Management System

Comprehensive 3×3 grid workspace system with names:

**Default Layout**:

```

0: Browser | 1: Chat | 2: Terminal

3: Project1 | 4: Project2 | 5: Media

6: Documents| 7: Games | 8: System

```

**Key Shortcuts**:

**Managing Names**:

```bash

Show current workspace

workspace-names.sh current

List all names

workspace-names.sh list

Rename workspace

workspace-names.sh set 0 "Web Browser"

User customization

cp /etc/xdg/hypr/workspace-names.conf ~/.config/hypr/

echo "0=My Custom Name" >> ~/.config/hypr/workspace-names.conf

```

**Waybar Integration**: Widget shows current workspace number and name, click to open switcher.

9. External Application Integrations

The waybar includes optional widgets for Kartoza applications:

**Timesheet Widget** (`90-custom-timesheet.json`):

**Video Recorder Widget** (`90-custom-recorder.json`):

When these apps are not installed, widgets gracefully handle missing commands.

10. Theme and Branding

**Icon Theme**: Expects `config.kartoza.theme.iconTheme.name` from importing flake (defaults to Papirus)

**Kartoza Colors**:

**Greeter**: Uses regreet with Kartoza theming

11. Testing Changes

Before committing:

1. **Format**: `nix fmt`

2. **Check**: `nix flake check`

3. **Validate Hyprland**: `hyprland --verify-config --config dotfiles/hypr/hyprland.conf`

4. **Test Waybar**: `cd dotfiles/waybar && ./build-config.sh && waybar -c config -s style.css --log-level debug`

5. **Integration Test**: Import module in test NixOS configuration and rebuild

12. Common Development Tasks

**Adding New Hyprland Keybinding**:

1. Edit `dotfiles/hypr/hyprland.conf`

2. Use `bind = SUPER, key, action, params` syntax

3. Validate with `hyprland --verify-config`

**Adding New Waybar Widget**:

1. Create `dotfiles/waybar/config.d/90-custom-name.json`

2. Add corresponding script in `dotfiles/waybar/scripts/` if needed

3. Run `./build-config.sh`

4. Test with `waybar -c config -s style.css`

**Modifying Window Rules**:

1. Identify window class: `hyprctl clients`

2. Add rule in `dotfiles/hypr/hyprland.conf`

3. Format: `windowrulev2 = rule, class:^(classname)$`

**Updating Module Options**:

1. Edit `modules/hyprland-desktop.nix`

2. Add option in `options.kartoza.hyprland-desktop`

3. Implement in `config` section

4. Document in CLAUDE.md

13. Integration Notes

The module provides:

14. File Structure Reference

```

.

├── flake.nix # Main flake definition

├── modules/

│ └── hyprland-desktop.nix # NixOS module implementation

├── dotfiles/

│ ├── hypr/

│ │ ├── hyprland.conf # Main compositor config

│ │ ├── workspace-names.conf # Workspace name definitions

│ │ └── scripts/ # Hyprland utility scripts

│ ├── waybar/

│ │ ├── config.d/ # Modular JSON config files

│ │ ├── build-config.sh # JSON merge script

│ │ ├── style.css # Waybar styling

│ │ └── scripts/ # Waybar widget scripts

│ ├── wofi/ # Application launcher

│ ├── swaync/ # Notification daemon

│ └── fuzzel/ # Additional launcher

└── scripts/ # System utility scripts

```

Important Constraints

1. **Always validate Hyprland config** after changes using `hyprland --verify-config`

2. **Never edit waybar `config` directly** - use modular system and `build-config.sh`

3. **Preserve swaync layer configuration** as `"layer": "top"` (not overlay)

4. **Use XDG paths** - system configs in `/etc/xdg/`, user overrides in `~/.config/`

5. **Format before commit** - run `nix fmt` on all Nix files

6. **Test module integration** - changes deploy via NixOS rebuild when module is imported

When to Use This Skill