wayland-utilities

name	wayland-utilities
description	Use when configuring third-party Wayland utilities used alongside Hyprland. Trigger for: status bars (waybar, eww), application launchers (wofi, rofi-wayland, fuzzel, anyrun), notification daemons (mako, dunst, swaync), terminals (kitty, foot, alacritty, wezterm), screenshot tools (grim, slurp, hyprshot, grimblast), clipboard (cliphist, wl-clipboard), display picker/OSDs (swayosd, avizo), file managers on Wayland. Provides decision matrices to help the user choose between alternatives and reference configurations.
compatibility	opencode
metadata	{"audience":"end-user","scope":"third-party-wayland","language":"es"}

wayland-utilities

Utilidades de terceros (no oficiales del ecosistema Hypr*) que el usuario combina con Hyprland: barras, lanzadores, notificaciones, terminales, screenshots, etc. Provee matriz de decisión para elegir entre alternativas + configs de referencia.

Reglas generales: prefiere herramientas nativas Wayland. Apps Wayland reducen latencia, integran mejor con gestos y no requieren XWayland (consume más memoria).

Decision matrix

Categoría	Recomendado	Alternativas	Cuándo elegir cada uno
Status bar	waybar	eww, ironbar	waybar = mainstream, máxima compatibilidad de módulos y temas. eww = control total (yuck/scss), curva alta. ironbar = ligero Rust, módulos JSON.
App launcher	wofi	rofi-wayland, fuzzel, anyrun, hyprlauncher	wofi = simple, GTK3, fácil tematizar. fuzzel = ligero, nativo Wayland, sin GTK. rofi-wayland = power user (modes), curva moderada. anyrun = plugins Rust. hyprlauncher = del ecosistema (ver hypr-ecosystem).
Notification daemon	mako	dunst, swaync	mako = nativo Wayland, simple, no panel. dunst = legacy más probado, panel ausente. swaync = con panel/historial GTK, más feature-rich.
Terminal	kitty	foot, alacritty, wezterm	kitty = features (imágenes, ligaduras, sessions), GPU. foot = ligero nativo Wayland, perfecto sin GPU. alacritty = mínimo cross-platform, sin tabs. wezterm = full-featured, multiplexor integrado, Lua config.
Screenshot	hyprshot	grim+slurp, grimblast	hyprshot = wrapper específico Hyprland (carpetas, regions, workspaces). grim+slurp = primitivos compose (lo que usa hyprshot). grimblast = wrapper sway-derived.
Clipboard manager	cliphist (+ wl-clipboard)	clipman	cliphist = simple, historial; usa wl-clipboard para clip.
Display picker / volume OSD	swayosd	avizo, swayosd	swayosd = librsvg-based, mostrar cambios de volumen/brillo. avizo = más pequeño, GTK.
File manager	depende del DE preferido	thunar, nautilus, nemo, dolphin	thunar = ligero XFCE. nautilus = GNOME. nemo = Cinnamon, plugins. dolphin = KDE, más completo. Todos funcionan en Wayland.

Routing per utility

Waybar

• Config: ~/.config/waybar/config.jsonc (JSON con comentarios) + ~/.config/waybar/style.css.
• Iniciar: waybar o systemd user unit.
• Docs locales: references/docs-third-party/waybar-configuration.md, waybar-styling.md, waybar-modules.md.
• Recarga: pkill -SIGUSR2 waybar.
• Layer rule en Hyprland (blur etc.):

  hl.layer_rule({ match = { namespace = "waybar" }, blur = true, ignore_zero = true })
  

Mínimo config.jsonc:

{
    "layer": "top",
    "position": "top",
    "height": 32,
    "modules-left":   ["hyprland/workspaces", "hyprland/window"],
    "modules-center": ["clock"],
    "modules-right":  ["pulseaudio", "network", "battery", "tray"],

    "hyprland/workspaces": {
        "format": "{name}",
        "on-click": "activate"
    },
    "clock": { "format": "{:%H:%M  %d/%m}" },
    "pulseaudio": {
        "format": "{volume}% {icon}",
        "format-muted": "muted",
        "on-click": "pavucontrol"
    },
    "network": { "format-wifi": "{essid} {signalStrength}%", "format-ethernet": "  eth" },
    "battery": { "format": "{capacity}% {icon}", "states": { "warning": 30, "critical": 15 } }
}

Mínimo style.css:

* { font-family: "JetBrainsMono Nerd Font", sans-serif; font-size: 13px; }
window#waybar { background: rgba(30, 30, 46, 0.85); color: #cdd6f4; }
#workspaces button { padding: 0 8px; color: #6c7086; }
#workspaces button.active { color: #f5c2e7; }
#clock, #battery, #pulseaudio, #network, #tray { padding: 0 10px; }

wofi

• Config: ~/.config/wofi/config + ~/.config/wofi/style.css.
• Lanzar: wofi --show drun.
• Bind sugerido: hl.bind("SUPER + space", hl.dsp.exec_cmd("wofi --show drun")).
• Doc local: references/docs-third-party/wofi.md (manpage).

Ejemplo config:

show=drun
prompt=Search…
width=600
height=400
allow_images=true
image_size=24
matching=fuzzy

rofi (rofi-wayland)

• Paquete: rofi-wayland (Arch / CachyOS). NO el rofi clásico, que es X11.
• Config: ~/.config/rofi/config.rasi.
• Lanzar: rofi -show drun.
• Doc local: references/docs-third-party/rofi-wayland.md.

fuzzel

• Paquete: fuzzel.
• Config: ~/.config/fuzzel/fuzzel.ini.
• Doc local: references/docs-third-party/fuzzel.md.
• Más ligero que wofi, sin GTK.

mako

• Config: ~/.config/mako/config.
• Doc local: references/docs-third-party/mako.md.
• Activar: systemctl --user enable --now mako.service (o exec_cmd("mako") en autostart).

Ejemplo mínimo:

default-timeout=5000
border-radius=8
border-color=#cba6f7
background-color=#1e1e2e
text-color=#cdd6f4
font=JetBrainsMono Nerd Font 10
padding=10
margin=10
max-icon-size=48

dunst

• Config: ~/.config/dunst/dunstrc.
• Doc local: references/docs-third-party/dunst.md.
• Más opciones, también más viejo. Tiene panel via dunstctl.

swaync

• Config: ~/.config/swaync/config.json + ~/.config/swaync/style.css.
• Doc local: references/docs-third-party/swaync.md.
• Tiene panel con historial — ideal para usuarios que quieren centro de notificaciones tipo GNOME/macOS.

kitty

• Config: ~/.config/kitty/kitty.conf.
• Doc local: references/docs-third-party/kitty.md (huge, ~239KB).
• Bind: hl.bind("SUPER + Q", hl.dsp.exec_cmd("kitty")).
• Features: imágenes inline, ligaduras, splits/tabs nativos, sessions.

foot

• Config: ~/.config/foot/foot.ini.
• Doc local: references/docs-third-party/foot.md (manpage).
• Más ligero (~700KB binario). Server mode con footclient.

alacritty

• Config: ~/.config/alacritty/alacritty.toml (era YAML, ahora TOML desde 0.13).
• Doc local: references/docs-third-party/alacritty.md.
• Sin tabs/splits — combina con tmux/zellij.

wezterm

• Config: ~/.config/wezterm/wezterm.lua (Lua, igual filosofía que Hyprland).
• Doc local: references/docs-third-party/wezterm.md.
• Multiplexor integrado, SSH wrapper, tabs/splits.

Screenshots (hyprshot / grim + slurp)

hyprshot wrapper práctico:

paru -S hyprshot

Binds Hyprland:

hl.bind("PRINT",                       hl.dsp.exec_cmd("hyprshot -m output"))     -- monitor entero
hl.bind("SHIFT + PRINT",               hl.dsp.exec_cmd("hyprshot -m region"))     -- selección
hl.bind("CTRL + PRINT",                hl.dsp.exec_cmd("hyprshot -m window"))     -- ventana activa

grim + slurp primitivos:

grim -g "$(slurp)" - | wl-copy             # region al clipboard
grim ~/screenshots/$(date +%F-%H%M%S).png  # fullscreen a archivo

Permissions (Hyprland 0.55+ con enforce_permissions = true):

hl.permission("/usr/(bin|local/bin)/grim",      "screencopy", "allow")
hl.permission("/usr/(bin|local/bin)/hyprshot",  "screencopy", "allow")

Clipboard

sudo pacman -S wl-clipboard cliphist

Autostart en hyprland.lua:

hl.on("hyprland.start", function()
    hl.exec_cmd("wl-paste --type text  --watch cliphist store")
    hl.exec_cmd("wl-paste --type image --watch cliphist store")
end)

Bind para historial:

hl.bind("SUPER + SHIFT + V", hl.dsp.exec_cmd("sh -c 'cliphist list | wofi --dmenu | cliphist decode | wl-copy'"))

OSDs (swayosd)

Mostrar OSD para volumen/brillo:

paru -S swayosd

Reemplazar binds de volumen para que también muestren OSD:

hl.bind("XF86AudioRaiseVolume", hl.dsp.exec_cmd("swayosd-client --output-volume +5"), { locked = true, repeating = true })
hl.bind("XF86MonBrightnessUp",  hl.dsp.exec_cmd("swayosd-client --brightness +5"),     { locked = true, repeating = true })

Daemon (autostart):

hl.on("hyprland.start", function() hl.exec_cmd("swayosd-server") end)

Search tool

python3 scripts/search_hyprland_docs.py "module"             # buscar en todos los docs
python3 scripts/search_hyprland_docs.py --list               # listar 15 secciones
python3 scripts/search_hyprland_docs.py --update             # refrescar todos
python3 scripts/search_hyprland_docs.py --update waybar-modules

Cómo decidir cuándo agregar una utility

Orden de preferencia heurístico:

1. ¿Existe equivalente en ecosistema Hypr* (oficial)? → preferir Hypr* por consistencia. Ejemplos: hyprlauncher > wofi para integración tighter; hyprpicker > otros pickers.
2. ¿Existe nativo Wayland? → preferir sobre el equivalente X11+XWayland.
3. ¿Tiene mantenimiento activo + integración con hyprland-workspaces o similar? → preferir herramientas comunidad-Hyprland.
4. ¿Necesidad real? → si Hyprland ya hace algo (e.g., dimming via decoration.dim_inactive), no agregar utility extra.

Install (CachyOS / Arch)

sudo pacman -S waybar wofi rofi-wayland fuzzel mako dunst swaync \
              kitty foot alacritty wezterm \
              grim slurp wl-clipboard cliphist swayosd \
              thunar
paru -S hyprshot eww ironbar anyrun-git swww

Para detalles de paquetes / repos / kernels, ver skill cachyos-system.

Output guidelines

• Cuando proponer una utility nueva, mencionar: paquete (paru -S o pacman -S), path de config, bind sugerido en hyprland.lua, link al doc local.
• No mezclar X11-only utilities (e.g., i3-status, i3bar, rofi clásico) — Hyprland es Wayland.
• Para waybar, separar siempre config.jsonc (estructura/módulos) de style.css (apariencia).
• Para mako vs dunst vs swaync, preguntar al usuario si quiere panel con historial → swaync; si no → mako (más simple).