---
name: hypr-config
description: Configure and troubleshoot Hyprland safely in this dotfiles repo. Use when adding or changing monitor, bind, input, workspace, window rule, layer rule, layout, animation, env, startup, or runtime behavior in `.config/hypr/*.conf`, and when diagnosing config errors, layer-shell stacking/input issues, or post-reload regressions for Hyprland 0.55 docs / locally recorded runtime.
---

# Hypr Config

## Scope

Treat `.config/hypr/docs/agents/` as the canonical local reference for this repo.
Reference baseline: Hyprland `0.55.0` docs. Confirm locally installed runtime with `.config/hypr/docs/agents/version.md` / `hyprctl version` before relying on new options.

Edit only the smallest relevant config file. Keep the repo's split-config layout.

## Activation Boundaries

Use this skill for Hyprland config/runtime behavior.

Do not use this skill for generic Nix/Home Manager refactors unless the task includes Hyprland behavior or diagnostics.

## Required Workflow

1. Read the active config structure first:
   - `.config/hypr/docs/agents/structure.md`
2. Classify the issue before editing:
   - parse/syntax errors
   - layer/input/stacking behavior
   - runtime regression after reload
3. Confirm exact syntax and options in local docs before changing behavior.
4. Apply minimal edits in the appropriate sourced file.
5. Validate every `.conf` change with:
   - `hyprctl configerrors`
6. Reload only when needed:
   - `hyprctl reload`

If `hyprctl configerrors` reports issues, fix them before any further tuning.

## Failure Decision Tree

1. If `hyprctl configerrors` is non-empty, fix syntax/rules first.
2. If symptom is layer/input/overlay behavior, inspect:
   - `hyprctl layers`
   - `hyprctl clients`
   - `.config/hypr/docs/agents/layer-rules.md`
3. If symptom appears only after reload/startup, inspect live logs:
   - `hyprctl rollinglog -f`
4. If unresolved, return the smallest next diagnostic step and required evidence.

## NEVER

- Never skip `hyprctl configerrors` after editing `.conf` files.
- Never bundle unrelated config changes before a validation cycle.
- Never claim a fix without command evidence tied to the symptom.
- Never use broad regex selectors when a stable explicit selector is available.
- Never rely on high-frequency `hyprctl` polling loops; `hyprctl` is synchronous.

## Authoring Rules

- Respect comma-separated argument counts. Empty arguments still require separators.
- Use block nesting for subcategories (`general { snap { ... } }`), not `general:snap {`.
- Keep rule order intentional. Rules are evaluated top to bottom.
- Remember precedence: named rules evaluate before anonymous rules.
- Distinguish static and dynamic window effects:
  - static effects apply on window creation
  - dynamic effects can be adjusted at runtime (including with `setprop`)
- Prefer explicit `match:` props and stable selectors over broad regex rules.

## Reference Loading Strategy

Load local docs first. Use these paths directly:

- `.config/hypr/docs/agents/pitfalls.md` for syntax traps and script-path pitfalls.
- `.config/hypr/docs/agents/debugging.md` for first-line diagnostics.
- `.config/hypr/docs/agents/references/Variables.md` for option types/defaults.
- `.config/hypr/docs/agents/references/Keywords.md` for config keywords and sourcing.
- `.config/hypr/docs/agents/references/Binds.md` and `.config/hypr/docs/agents/references/Dispatchers.md` for key handling.
- `.config/hypr/docs/agents/references/Window-Rules.md` for window/layer rule behavior.
- `.config/hypr/docs/agents/references/Workspace-Rules.md` for workspace policies.
- `.config/hypr/docs/agents/references/Monitors.md` for monitor setup/scaling.
- `.config/hypr/docs/agents/references/Using-hyprctl.md` for runtime control semantics.

Escalate to upstream docs only when local docs do not cover the behavior.

## Config Decision Guide

- **Monitors and scaling:** `.config/hypr/docs/agents/references/Monitors.md`.
- **Base options and types:** `.config/hypr/docs/agents/references/Variables.md`.
- **Keywords and sourcing:** `.config/hypr/docs/agents/references/Keywords.md`.
- **Binds and submaps:** `.config/hypr/docs/agents/references/Binds.md` + `.config/hypr/docs/agents/references/Dispatchers.md`.
- **Window behavior:** `.config/hypr/docs/agents/references/Window-Rules.md`.
- **Layer behavior (bars/notifications/overlays):** `.config/hypr/docs/agents/references/Window-Rules.md` (Layer Rules section).
- **Workspace policy/default monitor/layout:** `.config/hypr/docs/agents/references/Workspace-Rules.md`.
- **Layout-specific tuning:** `.config/hypr/docs/agents/references/Dwindle-Layout.md`, `.config/hypr/docs/agents/references/Master-Layout.md`, `.config/hypr/docs/agents/references/Monocle-Layout.md`, `.config/hypr/docs/agents/references/Scrolling-Layout.md`.
- **Runtime control via CLI:** `.config/hypr/docs/agents/references/Using-hyprctl.md`.

## Runtime-Safe Iteration

When testing behavior, prefer temporary runtime changes first, then persist in config:

- `hyprctl keyword ...` for option experiments
- `hyprctl dispatch ...` for behavior checks
- `hyprctl getoption ...` for effective values

Batch multiple runtime operations when possible with `hyprctl --batch`.
Avoid high-frequency `hyprctl` loops; it is synchronous.

## Output Contract

Return these five items:

1. symptom bucket
2. files inspected or edited
3. commands run with key results
4. root-cause hypothesis with confidence
5. smallest next safe step

## Repo Notes

- Scripts referenced by config should use full path style consistent with this repo (`~/.config/hypr/runtime/<area>/...`).
- If scripts are introduced or moved, keep executable bit correct.