hypr-ecosystem

name	hypr-ecosystem
description	Use when configuring official Hypr ecosystem companion tools (separate from Hyprland core). Trigger when the user asks about: hyprlock (lock screen), hypridle (idle daemon), hyprpaper (wallpapers), hyprcursor (cursor themes), hyprpicker (color picker), hyprlauncher (app launcher), hyprsunset (color temperature), hyprpolkitagent (polkit auth), hyprshutdown, hyprsysteminfo, xdg-desktop-portal-hyprland (screen sharing, file pickers), hyprland-qt-support, hyprqt6engine, hyprpwcenter, hyprtoolkit. Do NOT use for hyprland.lua itself or for third-party tools like waybar/wofi/mako.
compatibility	opencode
metadata	{"audience":"end-user","scope":"hypr-ecosystem","language":"es","config_syntax":"hyprlang"}

hypr-ecosystem

Skill para los componentes oficiales del ecosistema Hypr* (todos en github.com/hyprwm/). Son herramientas separadas de Hyprland core, cada una con su propio archivo de configuración.

🚩 CRÍTICO: estos componentes siguen usando hyprlang/INI (.conf), NO Lua. Solo Hyprland core (el compositor) migró a Lua en 0.55+. No inducir sintaxis Lua donde no aplica.

Index of components

Componente	Función	Archivo de config	Doc local
hyprlock	lock screen	~/.config/hypr/hyprlock.conf	references/docs-wiki/hyprlock.md
hypridle	idle daemon (timeouts)	~/.config/hypr/hypridle.conf	references/docs-wiki/hypridle.md
hyprpaper	wallpapers	~/.config/hypr/hyprpaper.conf	references/docs-wiki/hyprpaper.md
hyprsunset	color temperature (nightlight)	~/.config/hypr/hyprsunset.conf	references/docs-wiki/hyprsunset.md
hyprlauncher	app launcher (alternativa Hypr* a wofi)	~/.config/hypr/hyprlauncher.conf	references/docs-wiki/hyprlauncher.md
hyprpicker	color picker GUI/CLI	— (no config, flags CLI)	references/docs-wiki/hyprpicker.md
hyprcursor	cursor theme manager	env vars (HYPRCURSOR_THEME, HYPRCURSOR_SIZE)	references/docs-wiki/hyprcursor.md
hyprpolkitagent	polkit auth agent	systemd unit user	references/docs-wiki/hyprpolkitagent.md
hyprshutdown	menú apagado (logout/reboot/shutdown)	—	references/docs-wiki/hyprshutdown.md
hyprsysteminfo	info del sistema (GUI)	—	references/docs-wiki/hyprsysteminfo.md
hyprpwcenter	centro de control energía	—	references/docs-wiki/hyprpwcenter.md
xdg-desktop-portal-hyprland	screen share, file pickers (XDG)	systemd	references/docs-wiki/xdg-desktop-portal-hyprland.md
hyprlang	parser de hyprlang (lib subyacente)	— (dev)	references/docs-wiki/hyprlang.md
aquamarine	render backend (lib subyacente)	— (dev)	references/docs-wiki/aquamarine.md
hyprgraphics	graphics utils (lib)	— (dev)	references/docs-wiki/hyprgraphics.md
hyprtoolkit	GUI toolkit (lib)	— (dev)	references/docs-wiki/hyprtoolkit.md
hyprland-qt-support / hyprqt6engine	integración Qt	—	references/docs-wiki/hyprland-qt-support.md, references/docs-wiki/hyprqt6engine.md
hyprland-guiutils	utilidades GUI (incluye gestor de permissions)	—	references/docs-wiki/hyprland-guiutils.md

Las últimas filas (libs, Qt support, guiutils) son de bajo uso para usuario final. Útiles cuando: el usuario quiere apps Qt6 nativas (hyprqt6engine) o un GUI para gestionar permissions (hyprland-guiutils).

Search tool

python3 scripts/search_hyprland_docs.py "lock_cmd"           # buscar en todos los docs
python3 scripts/search_hyprland_docs.py --list               # listar las 20 secciones
python3 scripts/search_hyprland_docs.py --update             # refrescar todos
python3 scripts/search_hyprland_docs.py --update hyprlock    # solo uno

Common workflows

Lockscreen automático tras N minutos (hypridle + hyprlock)

~/.config/hypr/hyprlock.conf (mínimo):

background {
    monitor =
    path = screenshot
    blur_passes = 3
    blur_size = 8
}

input-field {
    monitor =
    size = 250, 50
    position = 0, -80
    halign = center
    valign = center
}

~/.config/hypr/hypridle.conf:

general {
    lock_cmd       = pidof hyprlock || hyprlock     # evita arrancar 2 hyprlock
    before_sleep_cmd = loginctl lock-session         # lock antes de suspend
    after_sleep_cmd  = hyprctl dispatch dpms on      # despertar bien
}

listener {
    timeout    = 300                                 # 5 min
    on-timeout = brightnessctl -s set 10             # bajar brillo
    on-resume  = brightnessctl -r                    # restaurar
}

listener {
    timeout    = 600                                 # 10 min
    on-timeout = loginctl lock-session               # lock
}

listener {
    timeout    = 900                                 # 15 min
    on-timeout = hyprctl dispatch dpms off           # apagar monitor
    on-resume  = hyprctl dispatch dpms on
}

Activar servicio (systemd user):

systemctl --user enable --now hypridle.service

Bind manual en hyprland.lua (Hyprland core):

hl.bind("SUPER + L", hl.dsp.exec_cmd("hyprlock"))

Wallpaper estático (hyprpaper)

~/.config/hypr/hyprpaper.conf:

preload = ~/Pictures/wallpapers/main.jpg

wallpaper = DP-1, ~/Pictures/wallpapers/main.jpg
wallpaper = HDMI-A-1, ~/Pictures/wallpapers/secondary.jpg

# Misc
splash = false
ipc = on

Activar (autostart desde hyprland.lua):

hl.on("hyprland.start", function() hl.exec_cmd("hyprpaper") end)

Wallpaper rotativo (hyprpaper + systemd timer)

hyprpaper no rota nativo. Usar IPC para cambiar al vuelo:

hyprctl hyprpaper preload ~/Pictures/wallpapers/2.jpg
hyprctl hyprpaper wallpaper "DP-1,~/Pictures/wallpapers/2.jpg"

Script ~/.local/bin/rotate-wallpaper.sh + systemd --user timer cada 10 min. Alternativa: swww (es de terceros, va en wayland-utilities).

Color temperature / nightlight (hyprsunset)

~/.config/hypr/hyprsunset.conf:

max-gamma = 100
profile {
    time = 6:30
    identity = true
}
profile {
    time = 19:30
    temperature = 3500
    gamma = 0.8
}

Servicio:

systemctl --user enable --now hyprsunset.service

Manual con bind:

hl.bind("SUPER + N", hl.dsp.exec_cmd("hyprctl hyprsunset temperature 3500"))

Polkit agent (hyprpolkitagent)

Necesario para que apps pidan password GUI (e.g. pkexec, partition managers). Servicio user:

systemctl --user enable --now hyprpolkitagent.service

Screen sharing en Discord / OBS / Zoom (xdg-desktop-portal-hyprland)

sudo pacman -S xdg-desktop-portal-hyprland
systemctl --user enable --now xdg-desktop-portal-hyprland.service

Si comparte pantalla en negro: instalar grim y dar permiso vía permissions de Hyprland — ver skill hyprland-config (recipe Permissions).

Launcher (hyprlauncher vs wofi/rofi)

hyprlauncher es la alternativa oficial del ecosistema. Más integrada pero menos featureful que rofi. Para comparativa, ver skill wayland-utilities. Bind sugerido:

hl.bind("SUPER + R", hl.dsp.exec_cmd("hyprlauncher"))

Cursor theme (hyprcursor)

Hyprland prefiere temas en formato hyprcursor. Si solo tienes xcursor, sigue funcionando vía fallback. Para usar:

hl.env("HYPRCURSOR_THEME", "Bibata-Modern-Ice")
hl.env("HYPRCURSOR_SIZE",  "24")
hl.env("XCURSOR_THEME",    "Bibata-Modern-Ice")    -- fallback XWayland
hl.env("XCURSOR_SIZE",     "24")

Listar instalados:

ls /usr/share/icons/

Instalar nuevos:

paru -S bibata-cursor-theme    # XCursor (auto-convertido)
paru -S rose-pine-hyprcursor   # nativo hyprcursor

Integration with Hyprland core

Los binds que invocan ecosistema viven en ~/.config/hypr/hyprland.lua, pero los configs específicos del ecosistema en ~/.config/hypr/<componente>.conf. Ejemplos:

hl.bind("SUPER + L",                hl.dsp.exec_cmd("hyprlock"))               -- lock manual
hl.bind("SUPER + R",                hl.dsp.exec_cmd("hyprlauncher"))           -- launcher
hl.bind("SUPER + P",                hl.dsp.exec_cmd("hyprpicker -a"))          -- color picker → clipboard
hl.bind("SUPER + SHIFT + ESCAPE",   hl.dsp.exec_cmd("hyprshutdown"))           -- power menu
hl.bind("CTRL + ALT + Print",       hl.dsp.exec_cmd("hyprshot -m output"))     -- screenshot fullscreen

systemd units to enable (user)

systemctl --user enable --now hypridle.service
systemctl --user enable --now hyprpolkitagent.service
systemctl --user enable --now hyprpaper.service           # si quieres autostart vía systemd
systemctl --user enable --now hyprsunset.service          # si configurado
systemctl --user enable --now xdg-desktop-portal-hyprland.service

Verificar:

systemctl --user status hypridle hyprpolkitagent hyprpaper hyprsunset xdg-desktop-portal-hyprland

Install (CachyOS / Arch)

La mayoría están en repos oficiales o AUR:

sudo pacman -S hyprlock hypridle hyprpaper hyprsunset hyprcursor hyprpicker hyprpolkitagent xdg-desktop-portal-hyprland
paru -S hyprlauncher hyprshutdown hyprsysteminfo hyprpwcenter         # algunos viven en AUR

Para detalles de paquetes / repositorios CachyOS, consultar skill cachyos-system.

Output guidelines

• Sintaxis: hyprlang .conf (bloques key { ... }, asignaciones key = value, comentarios #). NO Lua.
• Validar antes de proponer: usar python3 scripts/search_hyprland_docs.py <key> para confirmar nombres de opciones.
• Coordinar con hyprland-config: cuando un workflow involucra binds, dejar claro que el bind vive en hyprland.lua (Lua) y el config del componente en su .conf (hyprlang).
• Para activar servicios, usar systemctl --user (no system-wide).