hyprland-config

name	hyprland-config
description	Use when configuring Hyprland 0.55+ core via ~/.config/hypr/hyprland.lua (Lua syntax). Trigger for: keybindings (hl.bind), monitors (hl.monitor), window/workspace rules, dispatchers (hl.dsp.*), animations, gestures, input/touchpad, layouts (dwindle, master, scrolling, monocle, custom), decoration/blur, env vars, autostart, permissions, tearing, multi-GPU, NVIDIA setup, hyprctl debugging. Do NOT use for ecosystem components (hyprlock/hypridle/hyprpaper) — those have their own skill.
compatibility	opencode
metadata	{"audience":"end-user","scope":"hyprland-core","language":"es","hyprland_version":"0.55+","config_syntax":"lua"}

hyprland-config

Configuración del core de Hyprland 0.55+ vía ~/.config/hypr/hyprland.lua en sintaxis Lua.

⚠️ Hyprland 0.55+ usa Lua exclusivamente. La sintaxis hyprlang antigua (bind = SUPER, Q, exec, kitty) está removida, no solo deprecada. Si ves un .conf con esa sintaxis, hay que migrar.

Los componentes del ecosistema (hyprlock, hypridle, hyprpaper, …) sí siguen usando hyprlang .conf — pero ese trabajo es del skill hypr-ecosystem, no este.

File location and loading

• Archivo: ~/.config/hypr/hyprland.lua (uno solo, o split en módulos — ver recipe 10 de examples-lua.md).
• Carga: Hyprland lo lee al iniciar. Cambios se aplican con hyprctl reload (no requiere reinicio, salvo permissions que sí lo exige).
• Log: ~/.local/share/hyprland/hyprland.log.

Sources of truth (loading order para razonar)

1. references/example-hyprland.lua — copia del ejemplo oficial del repo hyprwm/Hyprland. Si dudas de la API, mira aquí primero.
2. references/examples-lua.md — 10 recetas working (minimal, multi-monitor, gaming, productivity, laptop, tiling power user, NVIDIA, rice, app rules, modular).
3. references/migration-table.md — equivalencias hyprlang → Lua para migrar configs viejos.
4. references/docs-wiki/ — 30 docs descargados de wiki.hypr.land (estructura basics/, layouts/, advanced/, getting-started/).

Search tool

python3 scripts/search_hyprland_docs.py "gaps_in"           # buscar término
python3 scripts/search_hyprland_docs.py "hl.bind"           # ejemplos de bind
python3 scripts/search_hyprland_docs.py --list              # listar las 30 secciones
python3 scripts/search_hyprland_docs.py --update            # refrescar todos los docs vía jina.ai
python3 scripts/search_hyprland_docs.py --update binds      # refrescar solo una sección

El script imprime contexto (2 líneas antes + 10 después) por cada match, con URL fuente.

Primitivas Lua de Hyprland (cheat sheet)

Primitiva	Uso
hl.config({...})	establece variables de sección (general, decoration, input, dwindle, master, scrolling, misc, animations, gestures, …)
hl.monitor({...})	declara un monitor
hl.bind(keys, dispatcher [, flags])	keybind
hl.dsp.*	dispatchers: exec_cmd, window.close/float/fullscreen/pseudo/pin/drag/resize/move/group_*, focus, workspace.toggle_special, layout, exit, …
hl.window_rule({ name=, match={...}, ...props })	regla de ventana
hl.workspace_rule({ workspace=, ...props })	regla de workspace
hl.layer_rule({ match={ namespace=... }, ... })	regla de layer (waybar, rofi, …)
hl.env(key, value [, { force=true }])	variable de entorno
hl.curve(name, { type="bezier"|"spring", ... })	curva de animación
hl.animation({ leaf=, enabled=, speed=, bezier=, spring=, style= })	animar un elemento
hl.gesture({ fingers=, direction=, action= })	gesto touchpad
hl.device({ name=, ...props })	config por-dispositivo
hl.permission(regex, capability, action)	permiso (necesita ecosystem.enforce_permissions = true)
hl.exec_cmd("...")	ejecutar al cargar config
hl.on("hyprland.start", function() ... end)	autostart (reemplaza exec-once)
require("modulename")	cargar modulename.lua del mismo directorio
hl.submap("name") y hl.submap_bind(...)	submaps (modos) — verificar nombre exacto en docs-wiki/basics/binds.md

Cada hl.bind(...), hl.window_rule(...) y hl.layer_rule(...) devuelve un handle con :set_enabled(true/false):

local b = hl.bind("SUPER + Q", hl.dsp.window.close())
b:set_enabled(false)   -- deshabilitar dinámicamente

Common tasks

Añadir un keybind

hl.bind("SUPER + Return", hl.dsp.exec_cmd("kitty"))

Flags en el 4º argumento (tabla): { locked = true, repeating = true, mouse = true, release = true }.

Reglas de ventana

hl.window_rule({ match = { class = "firefox" },              opacity = "1.0 0.9" })
hl.window_rule({ match = { class = "Picture-in-Picture" },   float = true, pin = true })
hl.window_rule({ match = { workspace = "1" },                no_anim = true })
hl.window_rule({ name = "no-max", match = { class = ".*" }, suppress_event = "maximize" })

El match ya no requiere ^(...)$ — usa string directo o regex Lua (.*).

Monitor

hl.monitor({ output = "DP-1", mode = "2560x1440@165", position = "0x0", scale = 1 })
hl.monitor({ output = "desc:Dell U2720Q", mode = "highres", position = "auto", scale = 1.5 })
hl.monitor({ output = "", mode = "preferred", position = "auto", scale = "auto" })  -- fallback

Cambiar layout

hl.config({ general = { layout = "scrolling" } })   -- dwindle | master | scrolling | monocle | custom

NVIDIA (mínimo razonable)

Ver receta 7 en references/examples-lua.md. Variables clave: LIBVA_DRIVER_NAME=nvidia, GBM_BACKEND=nvidia-drm, __GLX_VENDOR_LIBRARY_NAME=nvidia. Coordinarse con skill cachyos-system para instalar nvidia-dkms.

Tearing (gaming)

hl.config({ general = { allow_tearing = true } })
hl.window_rule({ match = { class = "steam_app_.*" }, immediate = true })

Permissions (0.55+, requiere restart de Hyprland)

hl.config({ ecosystem = { enforce_permissions = true } })
hl.permission("/usr/(bin|local/bin)/grim", "screencopy", "allow")
hl.permission("/usr/(lib|libexec|lib64)/xdg-desktop-portal-hyprland", "screencopy", "allow")

Submap (modo resize, hjkl)

Ver receta 6 en examples-lua.md. Si el nombre exacto de la API (hl.submap, hl.submap_bind) no aparece en docs-wiki/basics/binds.md, ejecutar python3 scripts/search_hyprland_docs.py submap para confirmar.

Modular split

-- hyprland.lua (entry)
require("monitors")
require("binds")
require("rules")

Cada módulo es un archivo .lua en el mismo directorio (sin extensión en la llamada).

Migration from hyprlang

Si el usuario tiene ~/.config/hypr/hyprland.conf con sintaxis antigua:

1. Backup: cp ~/.config/hypr/hyprland.conf ~/.config/hypr/hyprland.conf.bak.
2. Crear hyprland.lua en el mismo directorio.
3. Mapear sección por sección usando references/migration-table.md. Tabla completa cubre: sections, monitors, binds (incl. flags bindl/bindr/binde/bindm), window/workspace/layer rules, animations, curves, env vars, gestures, autostart, sourcing, permissions.
4. Probar con hyprctl reload (verás errores en stderr de Hyprland o en el log).
5. Cuando funcione, borrar hyprland.conf (Hyprland 0.55+ lo ignora).

Debugging workflow

hyprctl version                                # 0.55+
hyprctl monitors                               # estado de monitores
hyprctl clients                                # ventanas + workspaces
hyprctl workspaces                             # workspaces existentes
hyprctl devices                                # input devices
hyprctl getoption general:gaps_in              # leer valor concreto
hyprctl plugin list                            # plugins activos
tail -F ~/.local/share/hyprland/hyprland.log   # log en tiempo real

Para errores de sintaxis Lua: Hyprland los reporta en el log al cargar y a stderr. Si hace hyprctl reload con un error grave, no se aplican los cambios.

Output guidelines

• Solo emitir código Lua para Hyprland core. Nunca generar .conf con hyprlang para Hyprland.
• Usar local var = "..." para reusar valores. Importar módulos con require("...").
• Tablas anidadas con indentación 4 espacios, alineadas para legibilidad cuando hay varios campos.
• Validar nombres de dispatchers contra docs-wiki/basics/dispatchers.md antes de proponer uno raro.
• Mostrar al usuario en qué archivo va cada cambio y dónde insertarlo (al final, en sección X, …).
• Cuando agregues una primitiva nueva, citar la URL: e.g. # Ver: wiki.hypr.land/Configuring/Basics/Binds/.