Niri Desktop Configuration Skill

User: aps OS: CachyOS (Arch-based) Compositor: Niri (scrolling tiling Wayland) Desktop Shell: Noctalia (quickshell-based)

Architecture Overview

Noctalia is a quickshell-based desktop shell that replaces multiple components:

• Status Bar - Built-in (replaces Waybar)
• Notifications - Built-in (replaces Mako/dunst)
• Lock Screen - Built-in with PAM auth (replaces gtklock/swaylock)
• OSD - Built-in (replaces SwayOSD)
• App Launcher - Built-in with clipboard history
• Control Center - Built-in system menu
• Wallpaper - Built-in with transitions (replaces swww)
• Theme System - Auto-applies to 13 apps via templates + user templates

Other tools:

• Terminals: Ghostty (primary), Alacritty (floating)
• Editor: Zed
• Browser: Zen Browser + Brave
• Shell: Fish with Starship prompt
• Clipboard: cliphist + wl-clipboard

Key Config Locations

Important: How to Make Changes

Noctalia settings: Edit ~/.config/noctalia/settings.json (single 600+ line file)

• Keybinds, widgets, colors, behaviors all in one place
• Changes apply via IPC or restart Noctalia

Niri keybinds: Edit ~/.config/niri/cfg/keybinds.kdl (not main config.kdl)

Theme switching: Handled natively by Noctalia (via UI or IPC).

Window rules: Edit ~/.config/niri/cfg/rules.kdl

Noctalia Shell (quickshell-based)

What Noctalia Provides

• Status Bar - Floating bar with widgets (replaces Waybar)
• Notifications - Built-in notification daemon (replaces Mako)
• Lock Screen - Integrated lock screen with PAM auth (replaces gtklock)
• OSD - Volume/brightness on-screen display (replaces SwayOSD)
• App Launcher - Built-in launcher with clipboard history
• Control Center - System menu (network, bluetooth, power, etc.)
• Wallpaper - Built-in wallpaper management (replaces swww)

Noctalia Config Files

Main Settings: ~/.config/noctalia/settings.json

• All UI configuration in one file (600+ lines)
• Bar widgets, keybinds, colors, behaviors all configured here

Current Colors: ~/.config/noctalia/colors.json

• Material You style color scheme
• Auto-generated based on wallpaper/theme

Noctalia Theming

Noctalia auto-generates themed configs for: ghostty, alacritty, walker, niri, zed, gtk3/4, btop, cava, zenBrowser, mangoHud, qt, foot, and KDE apps. See the templates.activeTemplates section in settings.json.

User Templates: Enable in Settings → Color Scheme → Templates → Advanced → User templates

• Templates defined in ~/.config/noctalia/user-templates.toml
• Template files in ~/.config/noctalia/templates/
• Auto-regenerate when theme changes
• Currently used for: Starship prompt

Noctalia IPC Commands

# Lock screen
qs -c noctalia-shell --lock

# Launch app launcher
qs -c noctalia-shell --launcher

# Open control center
qs -c noctalia-shell --control-center

# Change wallpaper
qs -c noctalia-shell --set-wallpaper /path/to/wallpaper

# Set color scheme (triggers template regeneration)
qs -c noctalia-shell ipc call colorScheme set <ThemeName>

User Templates System

Config: ~/.config/noctalia/user-templates.toml

Template syntax: {{colors.name.mode.format}}

• Example: {{colors.primary.default.hex}}
• Colors: primary, secondary, tertiary, error, surface, on_surface, etc.
• Modes: default, dark, light
• Formats: hex, rgb, rgba, hsl, red, green, blue, etc.

Starship template: ~/.config/noctalia/templates/starship.toml

• Uses {{colors.primary.default.hex}} for accent color
• Auto-generated at ~/.config/starship.toml on theme change

Niri Configuration

Modular config structure in ~/.config/niri/:

niri/
├── config.kdl           # Main entry point
├── cfg/
│   ├── autostart.kdl    # Startup apps
│   ├── keybinds.kdl     # Keybindings
│   ├── display.kdl      # Monitor outputs
│   ├── input.kdl        # Keyboard/touchpad
│   ├── layout.kdl       # Layout settings
│   ├── rules.kdl        # Window rules
│   ├── misc.kdl         # Environment variables
│   ├── animation.kdl    # Animations
│   └── noctalia.kdl     # Noctalia-specific colors

Startup Applications

Defined in ~/.config/niri/cfg/autostart.kdl:

• polkit-kde-authentication-agent-1 (authentication dialogs)
• Noctalia shell (qs -c noctalia-shell)

Keybinds

Keybinds are defined in ~/.config/niri/cfg/keybinds.kdl. Common binds include terminal, browser, editor, lock screen, and launcher. Check the file for current bindings.

Theme System

Noctalia v5 natively manages themes and wallpapers.

How Themes Work

Colors: Noctalia generates the color scheme and stores it in ~/.config/noctalia/colors.json. All apps (including Starship via user templates) get themed automatically when you change the color scheme.

Available Themes: Themes are selected directly through the Noctalia Control Center / Settings UI.

What Happens When You Switch Themes

1. Noctalia generates a new color scheme and regenerates all themed configs (including Starship via user template).
2. Noctalia updates the wallpaper natively.

All apps update automatically - no manual template substitution needed.

Authentication & PAM

PAM Configuration (Lock Screen vs Login)

Key Insight: Fingerprint login at greetd doesn't unlock gnome-keyring (needs actual password). We separate PAM configs:

• Login (greetd): /etc/pam.d/login → includes system-auth → NO fingerprint (requires password for keyring)
• Lock Screen (Noctalia): /etc/pam.d/noctalia-lock → HAS fingerprint (keyring already unlocked)

Lock Screen PAM (/etc/pam.d/noctalia-lock)

#%PAM-1.0
# Noctalia lock screen - includes fingerprint auth

auth       sufficient   /usr/lib/security/pam_fprintd.so timeout=-1
auth       include      system-auth

account    include      system-auth
password   include      system-auth
session    include      system-auth

Note: Use full path /usr/lib/security/pam_fprintd.so - Noctalia may not find it otherwise. Note: timeout=-1 keeps fingerprint reader active indefinitely.

Noctalia PAM Service Configuration

Noctalia reads NOCTALIAPAMSERVICE env var to determine which PAM service to use. Set via systemd override:

Override file: ~/.config/systemd/user/noctalia.service.d/pam.conf

[Service]
Environment=NOCTALIA_PAM_SERVICE=noctalia-lock

After creating/editing, run: systemctl --user daemon-reload && systemctl --user restart noctalia.service

Screen Lock

Noctalia provides the lock screen with PAM authentication.

Auto-lock: Handled natively by Noctalia v5's built-in idle management (replacing swayidle).

Fingerprint Auth (fprintd)

Enroll fingerprints: fprintd-enroll

Result of this setup:

• greetd login: Password only (unlocks gnome-keyring properly)
• Noctalia lock screen: Fingerprint OR password (keyring already unlocked from login)

Account Lockout (pam_faillock)

Incorrect password attempts trigger a temporary lockout via pam_faillock.so (configured in /etc/security/faillock.conf).

• Limit: Currently set to 5 attempts.
• Duration: 10 minutes (600 seconds).
• Reset: Run sudo faillock --user aps --reset. Alternatively, since records are stored in temporary RAM (/var/run/faillock), simply rebooting the system instantly clears the lockout.

Polkit Agent

Agent: /usr/lib/polkit-kde-authentication-agent-1

• Started automatically with Niri
• Provides authentication dialogs for privileged operations

Login Manager (greetd + noctalia-greeter)

Uses greetd with noctalia-greeter to match the Noctalia shell UI.

Config files:

• /etc/greetd/config.toml - Main greetd config (launches /usr/bin/noctalia-greeter-session)
• /var/lib/noctalia-greeter/greeter.toml - Greeter settings (default session/user)
• /var/lib/noctalia-greeter/sync.toml - Auto-synced appearance settings

Features: matches Noctalia color scheme and wallpaper, remembers last user/session, supports session selection.

Syncing appearance: Run Settings → Security → Noctalia Greeter → Sync Now from the Noctalia shell to sync wallpaper and colors. If on seatd without logind, run: pkexec noctalia-greeter-apply-appearance "$XDGRUNTIMEDIR/noctalia-greeter-sync" in a terminal after staging.

Display Scaling & Multiple Monitors: If the greeter looks excessively large/pixelated natively on high-DPI screens, wlroots is likely applying scale = 2.0 automatically. To force scale = 1.0 while keeping multiple monitors active (and avoiding TOML parse errors), use global output settings with a combined layout string in /var/lib/noctalia-greeter/greeter.toml:

[output]
layout = "eDP-1:0,0; HDMI-A-1:1920,0"
scale = 1.0

Clipboard

Uses wl-clipboard with cliphist for history. Clipboard watching is configured in Noctalia settings.json - look for clipboard-related settings in the appLauncher section.

Common Tasks

Change a keybinding

Edit ~/.config/niri/cfg/keybinds.kdl

Add a window rule

Edit ~/.config/niri/cfg/rules.kdl. Example patterns:

window-rule {
    match app-id=r#"^firefox$"#
    open-maximized true
}

Adjust gaps or focus ring

Edit ~/.config/niri/cfg/layout.kdl

Reload after changes

• Niri: Changes auto-reload
• Noctalia: Changes apply immediately via IPC

Add custom widget to Noctalia bar

Edit ~/.config/noctalia/settings.json in the bar.widgets.right (or left/center) array. Use CustomButton widget type to add custom buttons with icons, click handlers, and dynamic text from shell commands.

Create a new user template

1. Create template file in ~/.config/noctalia/templates/myapp.conf
2. Add to ~/.config/noctalia/user-templates.toml:

[templates.myapp]
input_path = "~/.config/noctalia/templates/myapp.conf"
output_path = "~/.config/myapp/theme.conf"
post_hook = "pkill -USR1 myapp"  # optional reload command

1. Use template syntax like {{colors.primary.default.hex}}
2. Trigger regeneration by changing theme

Auto-Generated Files

These files are managed automatically - edit their sources instead:

Git Repository

Dotfiles tracked at github.com/APS6/nox-config.

User Preferences

• Font: JetBrains Mono Nerd Font
• Location: Haldwani, Uttarakhand (weather)
• No emojis unless requested
• Prefers AI to make config changes

Maintenance Note

Remember: After making changes to any system components that are documented in this skill (themes, auth, keybinds, Noctalia config, etc.), update this skill file to reflect the current state. This ensures the AI has accurate information for future tasks.