niri

name: niri description: Guidance for editing niri window manager configuration files under home/dot_config/niri/. Use when the task involves niri config, keybinds, gestures, hot corners, layout, window rules, animations, input, displays, or autostart. user-invocable: false

Niri Window Manager Configuration

This skill provides domain knowledge for editing the niri tiling Wayland compositor config in this dotfiles repo.

Config Structure

The niri config lives in home/dot_config/niri/ and deploys to ~/.config/niri/. The main entry point is config.kdl, which includes all other files:

Source file	Deploys as	Purpose
`config.kdl`	`~/.config/niri/config.kdl`	Entry point — only `include` directives
`noctalia.kdl`	`~/.config/niri/noctalia.kdl`	Noctalia theme colors (focus-ring, border, shadow, tab-indicator)
`cfg/animation.kdl`	`~/.config/niri/cfg/animation.kdl`	Animation settings (currently off)
`cfg/autostart.kdl.tmpl`	`~/.config/niri/cfg/autostart.kdl`	Startup applications — chezmoi template
`cfg/decorations.kdl`	`~/.config/niri/cfg/decorations.kdl`	Window decorations (focus-ring, border, shadow — all off, overridden by theme)
`cfg/display.kdl`	`~/.config/niri/cfg/display.kdl`	Monitor/output configuration
`cfg/input.kdl`	`~/.config/niri/cfg/input.kdl`	Keyboard layout, touchpad, focus behavior
`cfg/keybinds.kdl`	`~/.config/niri/cfg/keybinds.kdl`	All key bindings inside a `binds {}` block
`cfg/layout.kdl`	`~/.config/niri/cfg/layout.kdl`	Layout gaps, preset column widths, centering
`cfg/misc.kdl`	`~/.config/niri/cfg/misc.kdl`	Environment variables, CSD preference, screenshots, hotkey overlay
`cfg/rules.kdl`	`~/.config/niri/cfg/rules.kdl`	Window and layer rules

KDL Format Patterns

Niri uses KDL for configuration. Common patterns in this config:

Spawn commands: spawn-at-startup "binary" "arg1" "arg2" or spawn-sh-at-startup "shell command" (the -sh variant runs through a shell)
Keybinds: Inside binds {}, each line is Mod+Key { action; } — optionally with properties like hotkey-overlay-title="...", allow-when-locked=true, cooldown-ms=150
Input: input { keyboard { xkb { layout "us,dk" } } touchpad { tap } }
Environment: environment { VAR_NAME "value" } inside cfg/misc.kdl
Outputs: output "NAME" { mode "WxH@rate" scale N }
Commented-out blocks: Niri uses /- before a node to comment out the entire block (not //)
Comments: // for line comments

Key Constraints

Final newlines are mandatory

All KDL files must end with a final newline. Niri's config parser may fail to process the last line otherwise. Always verify this when creating or editing files.

chezmoi template: `autostart.kdl.tmpl`

This file uses Go template syntax ({{ if .isWork }}...{{ end }}). The .tmpl suffix tells chezmoi to process it. The rendered output drops the .tmpl extension. Use chezmoi template variables (e.g. .isWork) for conditional blocks.

Environment variables may need shell config sync

If you add or change environment variables in cfg/misc.kdl's environment {} block that should also be available in shell sessions, you must update all three shell configs per the CLAUDE.md sync rules:

home/dot_bashrc
home/dot_config/fish/conf.d/config.fish
home/dot_config/powershell/Microsoft.PowerShell_profile.ps1

Platform filtering

Niri configs only deploy when .isNiri is true in chezmoi data (see home/.chezmoiignore.tmpl). The entire dot_config/niri directory is ignored on non-niri systems.

Niri Wiki Reference

For available configuration options, consult the niri wiki:

Configuration overview: https://github.com/YaLTeR/niri/wiki/Configuration:-Overview
Key bindings: https://github.com/YaLTeR/niri/wiki/Configuration:-Key-Bindings
Input: https://github.com/YaLTeR/niri/wiki/Configuration:-Input
Outputs: https://github.com/YaLTeR/niri/wiki/Configuration:-Outputs
Layout: https://github.com/YaLTeR/niri/wiki/Configuration:-Layout
Window rules: https://github.com/YaLTeR/niri/wiki/Configuration:-Window-Rules
Miscellaneous: https://github.com/YaLTeR/niri/wiki/Configuration:-Miscellaneous

Verification

After editing niri config files:

# Validate the niri config (checks deployed config at ~/.config/niri/)
niri validate

# Preview what chezmoi will deploy (useful for template files)
chezmoi diff