Skip to content

marceloeatworld/hyprland-ai-skill

hyprland

Flagged

This skill should be used when the user asks about "Hyprland configuration", "hyprland.lua", "hyprland.conf", "Hyprland Lua config", "hyprctl", "Hyprland keybinds", "Hyprland window rules", "Hyprland monitors", "Hyprland dispatchers", "Hyprland animations", "Hyprland workspaces", "Hyprland IPC", "Hyprland plugins", "hyprlock", "hypridle", "hyprpaper", "hyprcursor", "hyprpicker", "hyprsunset", "xdg-desktop-portal-hyprland", "Hyprland on NixOS", "Hyprland Home Manager", "Hyprland layouts", "Hyprland dwindle", "Hyprland master layout", "Hyprland FAQ", "Hyprland performance", "Hyprland Nvidia", "Hyprland screen sharing", "Hyprland special workspace", "Hyprland smart gaps", "Hyprland multi-monitor", "Hyprland tearing", or any topic related to configuring, troubleshooting, or extending the Hyprland Wayland compositor and its ecosystem tools.

Hyprland Documentation

Complete reference for the Hyprland Wayland compositor, auto-generated from the official wiki at https://wiki.hypr.land/.

The references/ directory contains the full, unmodified wiki markdown from https://github.com/hyprwm/hyprland-wiki, updated daily.

How to Use

  1. Identify the topic from the user's question and read the matching reference file from the tables below.
  2. Base answers on those files. If more detail is needed, fetch the latest docs from the raw GitHub URLs in Live Fetching.
  3. Since Hyprland 0.55, the config is Lua (~/.config/hypr/hyprland.lua): hl.config({...}), hl.bind(...), hl.monitor({...}), hl.window_rule({...}), hl.on(...). The old hyprlang format (hyprland.conf) is deprecated. Check the user's version with hyprctl version when in doubt.
  4. For Hyprland 0.54 and earlier, use hyprlang syntax and point the user to the versioned wiki at https://wiki.hypr.land/0.54.0/ (the reference files here track the current Lua docs).
  5. Split configs use Lua require("subdir/file"), not the old source = keyword.
  6. For NixOS users, note that hyprpm is unsupported on Nix — use Home Manager or the NixOS module for plugins.
  7. For troubleshooting, check references/faq.md first.

Reference Files

Configuration

TopicFile
Config file basics, Lua syntax, require, LSP stubsreferences/start.md
Variables / options (general, decoration, input, misc, etc.)references/variables.md
Keybinds (hl.bind, flags, submaps)references/binds.md
Dispatchers (hl.dsp.*, hl.dispatch)references/dispatchers.md
Window rules and layer rulesreferences/window-rules.md
Monitor configurationreferences/monitors.md
Autostart (hyprland.start event)references/autostart.md
Animations and bezier curvesreferences/animations.md
Workspace rules and smart gapsreferences/workspace-rules.md
Environment variablesreferences/environment-variables.md
Layouts (dwindle, master, scrolling, monocle, custom)references/layouts.md
Lua scripting, events, timers (hl.on, hl.exec_cmd)references/lua-scripting.md
Per-device input configreferences/devices.md
Notifications APIreferences/notifications.md
Performance tuningreferences/performance.md
XWaylandreferences/xwayland.md
Screen tearingreferences/tearing.md
Multi-GPUreferences/multi-gpu.md
Virtual GPUreferences/virtual-gpu.md
Permissionsreferences/permissions.md
Gesturesreferences/gestures.md
Systemd integration (graphical-session.target)references/systemd.md
Naming conventions (workspace, monitor, window selectors)references/naming-conventions.md
Lua code snippets and example configsreferences/code-snippets.md

Tools

TopicFile
hyprctl CLI usage (eval, repl, batch)references/hyprctl.md
IPC sockets and eventsreferences/ipc.md

Hypr Ecosystem

TopicFile
Hyprlock (screen lock)references/hyprlock.md
Hypridle (idle management)references/hypridle.md
Hyprpaper (wallpaper)references/hyprpaper.md
Hyprlauncher (app launcher)references/hyprlauncher.md
Hyprpicker (color picker)references/hyprpicker.md
Hyprsunset (blue light filter)references/hyprsunset.md
Hyprcursor (cursor themes)references/hyprcursor.md
XDPH (xdg-desktop-portal-hyprland)references/xdph.md
Hyprpolkitagent (polkit auth)references/hyprpolkitagent.md
Hyprshutdown (shutdown utility)references/hyprshutdown.md
Hyprsysteminfo (system info)references/hyprsysteminfo.md
Hyprpwcenter (power management)references/hyprpwcenter.md
Hyprland Qt supportreferences/hyprland-qt-support.md
Dev libraries (hyprtoolkit, hyprlang, hyprutils, aquamarine, etc.)references/hypr-libraries.md

Plugins

TopicFile
Plugin usage and developmentreferences/plugins.md

Platform-Specific

TopicFile
NixOS / Nix / Home Managerreferences/nix.md
Nvidia setupreferences/nvidia.md

Help

TopicFile
FAQ and troubleshootingreferences/faq.md
Getting started / installationreferences/getting-started.md
Useful utilities (bars, launchers, screenshots, systemd, etc.)references/useful-utilities.md
Crashes and bugsreferences/crashes-and-bugs.md
Contributing to Hyprlandreferences/contributing.md

Live Fetching

When reference files are insufficient, fetch the latest docs from raw GitHub:

https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/<section>/<page>.md

Paths are lowercase. Section index pages are _index.md. Examples:

  • https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/configuring/core/config-options.md
  • https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/configuring/core/advanced-configuration/using-hyprctl.md
  • https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/hypr-ecosystem/user/hyprlock.md
  • https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/nix/installing-hyprland-on-nixos.md

The <!-- source: ... --> header at the top of each reference file gives the matching wiki section.

Quick Reference (Hyprland 0.55+, Lua config)

Config file location

~/.config/hypr/hyprland.lua (or $XDG_CONFIG_HOME/hypr/hyprland.lua, override with Hyprland --config)

Options

hl.config({
    general = {
        border_size = 2,
        gaps_in = 5,
    },
})

Multiple hl.config() calls are allowed; each updates only what it receives.

Binds

hl.bind("SUPER + SHIFT + Q", hl.dsp.exec_cmd("firefox"))
hl.bind("SUPER + X", function()
    hl.dispatch(hl.dsp.window.float({ action = "toggle" }))
end)

Autostart

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

Window rules

hl.window_rule({
    match = { class = "firefox" },
    opacity = 0.9,
    float = true,
})

Monitors

hl.monitor({
    output = "DP-1",
    mode = "1920x1080@144",
    position = "0x0",
    scale = 1,
})

Split config

require("conf/binds")      -- ~/.config/hypr/conf/binds.lua

hyprctl runtime control

hyprctl reload
hyprctl eval 'hl.config({ general = { border_size = 3 } })'
hyprctl repl               # interactive Lua REPL
hyprctl --batch "..."

Legacy (Hyprland 0.54 and earlier, hyprlang)

Old-style ~/.config/hypr/hyprland.conf:

bind = MODS, key, dispatcher, params
general {
    border_size = 2
}
monitor = name, resolution@rate, position, scale

Full legacy docs: https://wiki.hypr.land/0.54.0/

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall