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.

FileKindSize
SKILL.mdskill md7.8 KB
references/.wiki-versionother50 B
references/animations.mdmarkdown6.1 KB
references/autostart.mdmarkdown770 B
references/binds.mdmarkdown24.0 KB
references/code-snippets.mdmarkdown16.5 KB
references/contributing.mdmarkdown19.4 KB
references/crashes-and-bugs.mdmarkdown5.9 KB
references/devices.mdmarkdown2.0 KB
references/dispatchers.mdmarkdown13.1 KB
references/environment-variables.mdmarkdown4.0 KB
references/faq.mdmarkdown13.8 KB
references/gestures.mdmarkdown8.4 KB
references/getting-started.mdmarkdown26.6 KB
references/hypr-libraries.mdmarkdown15.9 KB
references/hyprctl.mdmarkdown8.3 KB
references/hyprcursor.mdmarkdown2.2 KB
references/hypridle.mdmarkdown11.2 KB
references/hyprland-qt-support.mdmarkdown2.3 KB
references/hyprlauncher.mdmarkdown2.1 KB
references/hyprlock.mdmarkdown20.6 KB
references/hyprpaper.mdmarkdown3.4 KB
references/hyprpicker.mdmarkdown1.9 KB
references/hyprpolkitagent.mdmarkdown2.3 KB
references/hyprpwcenter.mdmarkdown436 B
references/hyprshutdown.mdmarkdown2.0 KB
references/hyprsunset.mdmarkdown4.8 KB
references/hyprsysteminfo.mdmarkdown457 B
references/ipc.mdmarkdown6.6 KB
references/layouts.mdmarkdown19.1 KB
references/lua-scripting.mdmarkdown9.6 KB
references/monitors.mdmarkdown14.1 KB
references/multi-gpu.mdmarkdown4.6 KB
references/naming-conventions.mdmarkdown4.7 KB
references/nix.mdmarkdown30.1 KB
references/notifications.mdmarkdown2.4 KB
references/nvidia.mdmarkdown1.3 KB
references/performance.mdmarkdown1.5 KB
references/permissions.mdmarkdown5.2 KB
references/plugins.mdmarkdown18.2 KB
references/start.mdmarkdown6.9 KB
references/systemd.mdmarkdown2.0 KB
references/tearing.mdmarkdown1.7 KB
references/useful-utilities.mdmarkdown47.4 KB
references/variables.mdmarkdown59.0 KB
references/virtual-gpu.mdmarkdown6.9 KB
references/window-rules.mdmarkdown19.2 KB
references/workspace-rules.mdmarkdown2.7 KB
references/xdph.mdmarkdown5.7 KB
references/xwayland.mdmarkdown2.0 KB
scripts/generate-references.shexecutablescript12.1 KB

references/code-snippets.md

View on GitHub
<!-- source: https://wiki.hypr.land/configuring/code-snippets -->
<!-- wiki commit: 41c7222 (2026-11-20 18:16:21 +0100) -->
<!-- auto-generated by scripts/generate-references.sh - DO NOT EDIT MANUALLY -->

---
weight: 60
title: Lua code snippets
---

## Code snippets

Code snippets provided on this page may prove useful as inspiration or straight-up copy-paste.

<!-- TODO: scrape DA WEB for snippets that may or may not be useful -->

### Per-layout binds

```lua
---@param bind_table table<HL.LayoutNamespace, HL.Dispatcher>
---@return fun()
local function layout_bind(bind_table)
    return function ()
        local workspace = hl.get_active_special_workspace() or hl.get_active_workspace()
        if not workspace then return end

        local layout = workspace.tiled_layout

        if bind_table[layout] then
            hl.dispatch(bind_table[layout])
        end
    end
end
```

Usage:

```lua
hl.bind("SUPER + A", layout_bind({
    scrolling = hl.dsp.layout("swapcol l"),  -- Scrolling: swap column with left one
    dwindle   = hl.dsp.layout("swapsplit"),  -- Dwindle: swap window split
    monocle   = hl.dsp.layout("cycleprev"),  -- Monocle and master: cycle prev window
    master    = hl.dsp.layout("cycleprev"),
}))

hl.bind("SUPER + D", layout_bind({
    scrolling = hl.dsp.layout("swapcol r"),   -- Scrolling: swap column with right one
    dwindle   = hl.dsp.layout("togglesplit"), -- Dwindle: toggle window split
    monocle   = hl.dsp.layout("cyclenext"),   -- Monocle and master: cycle next window
    master    = hl.dsp.layout("cyclenext"),
}))
```

### Minimize windows using special workspaces

This approach uses special workspaces to mimic the "minimize window" function, by using a single keybind to toggle the minimized state.
Note that one keybind can only handle one window.

```lua
hl.bind("SUPER + X", function ()
    if hl.get_workspace("special:minimized") then
        hl.dispatch(hl.dsp.window.move({ workspace = hl.get_active_workspace(), window = "tag:minimized" }))
        hl.dispatch(hl.dsp.window.clear_tags({ window = "tag:minimized" }))
    else
        hl.dispatch(hl.dsp.window.tag({ tag = "minimized", window = hl.get_active_window() }))
        hl.dispatch(hl.dsp.window.move({ workspace = "special:minimized", follow = false }))
    end
end)
```

### Share keybinds with nested sessions

When developing for Hyprland (or writing a plugin), you may want to share keybinds between your regular Hyprland session and a nested one.
To achieve this, add the following to your Lua config:

```lua
hl.define_submap("locked", function()
    hl.bind("catchall", hl.dsp.no_op(), { non_consuming = true })

    -- Emergency escape hatch
    hl.bind("CTRL + SHIFT + Escape", hl.dsp.submap("reset"))
end)

hl.on("window.active", function(window)
    if window and window.class == "aquamarine" then
        hl.dispatch(hl.dsp.submap("locked"))
    else
        hl.dispatch(hl.dsp.submap("reset"))
    end
end)
```

This allows you to use the same shortcuts in your host and nested Hyprland sessions, by preventing the host session from seeing the key presses if the nested session is focused.
Changing the active window or closing the nested session will restore your default keybinds.
The shortcut `CTRL + SHIFT + Escape` will also force your default keybinds back in case you need them.

### Smart gaps

To replicate "smart gaps"/"no gaps when only" from other WMs/compositors:

```lua
hl.workspace_rule({ workspace = "w[tv1]", gaps_out = 0, gaps_in = 0 })
hl.workspace_rule({ workspace = "f[1]", gaps_out = 0, gaps_in = 0 })
hl.window_rule({ match = { float = false, workspace = "w[tv1]" }, border_size = 0 })
hl.window_rule({ match = { float = false, workspace = "w[tv1]" }, rounding = 0 })
hl.window_rule({ match = { float = false, workspace = "f[1]" }, border_size = 0 })
hl.window_rule({ match = { float = false, workspace = "f[1]" }, rounding = 0 })
```

#### Smart gaps (ignoring special workspaces)

You can combine workspace selectors for more fine-grained control, for example, to ignore special workspaces:

```lua
hl.workspace_rule({ workspace = "w[tv1]s[false]", gaps_out = 0, gaps_in = 0 })
hl.workspace_rule({ workspace = "f[1]s[false]", gaps_out = 0, gaps_in = 0 })
hl.window_rule({ match = { float = false, workspace = "w[tv1]s[false]" }, border_size = 0 })
hl.window_rule({ match = { float = false, workspace = "w[tv1]s[false]" }, rounding = 0 })
hl.window_rule({ match = { float = false, workspace = "f[1]s[false]" }, border_size = 0 })
hl.window_rule({ match = { float = false, workspace = "f[1]s[false]" }, rounding = 0 })
```

### Float browsers' extension windows

All known browsers have the annoying "feature" of setting extension window titles to the browser's own name.
This function listens to opened windows and floats the matches:

```lua
hl.on("window.open", function(w)
    if w.class ~= "firefox" then return end
    if w.initial_title ~= "Mozilla Firefox" then return end

    local ff_windows = hl.get_windows({ class = "firefox" })
    if #ff_windows <= 1 then return end

    hl.dispatch(hl.dsp.window.float({ action = "set", window = w }))

    local sub
    sub = hl.on("window.title", function(tw)
        if tw.address ~= w.address then return end
        if tw.title == ""
            or tw.title == "Mozilla Firefox"
            or tw.title == "about:blank"
            or tw.title:match("^about:.*Mozilla Firefox$") then return end

        sub:remove()

        if tw.title:match("^Extension:") then
            hl.dispatch(hl.dsp.window.resize({ x = 800, y = 600, window = tw }))
            hl.dispatch(hl.dsp.window.center({ window = tw }))
            hl.dispatch(hl.dsp.focus({ window = tw }))
        else
            hl.dispatch(hl.dsp.window.float({ action = "unset", window = tw }))
        end
    end)
end)
```

### Open Tor Browser and Mullvad Browser at their default window size

Tor Browser and Mullvad Browser open at a window size shared by all their users, so nobody stands out by screen dimensions.
A tiled, maximized, or fullscreen window has a size of its own, and the browser letterboxes it to compensate.
See the [Tor Browser 9.0 release notes](https://blog.torproject.org/new-release-tor-browser-90/) and [TZP](https://github.com/arkenfox/TZP).

Float them so they keep their default size:

```lua
hl.window_rule({
    name = "privacy-browsers-float",
    match = { class = "^(Tor Browser|Mullvad Browser)$" },
    float = true,
    center = true,
    fullscreen_state = "0 0",
    suppress_event = "maximize",
})
```

Do not add a `size` rule for these windows.

### Config versioning

Some updates add breaking changes, which can be anticipated by looking at the Hyprland version.

You can make your configs conditional using `hl.version()`, e.g.:

```lua
if hl.version() == "0.55.2" then
    hl.config({
        general = {
            changed_property = "value"
        }
    })
else
    hl.notification.create({
        text = "You're using: ".. hl.version(),
        timeout = 10000
    })
end
```

### "Starts with" helper function

```lua
---@param string string
---@param prefix string
---@return boolean
local function starts_with(string, prefix)
    return string:find(prefix, 1, true) == 1
end
```

### Toggle animations/blur/etc hotkey

Easily toggling animations and other effects with a bind could be useful for temporarily having less distractions, or for saving battery on a laptop:

```lua
local game_mode = false

hl.bind("SUPER + F1", function ()
    if game_mode then
        hl.dispatch(hl.dsp.reload_config())
        return
    end

    hl.config({
        general = {
            gaps_in = 0,
            gaps_out = 0,
            border_size = 0,
        },

        animations = {
            enabled = false,
        },

        decoration = {
            shadow = { enabled = false },
            blur = { enabled = false },
            rounding = 0,
        }
    })

    game_mode = true
end)
```

### Cycle layout for current workspace

To change the layout of the current workspace, you can use this bind:

```lua
hl.bind("SUPER + tab", function ()
    local layouts   = { "scrolling", "dwindle", "master", "monocle" }
    local next_layout

    local workspace = hl.get_active_special_workspace() or hl.get_active_workspace()
    if not workspace then return end

    for i = 1, #layouts do
        if layouts[i] == workspace.tiled_layout then
            next_layout = layouts[ i % #layouts + 1 ]
            goto dispatch
        end
    end

    ::dispatch::
    hl.workspace_rule({ workspace = workspace.addressable_name, layout = next_layout })
end)
```

### Windows Magnifier-like cursor zoom

These binds adjust the zoom factor, which zooms into your entire screen and moves to keep the cursor in view.
This acts similarly to Windows Magnifier, in its full-screen mode.

```lua
local MAX_ZOOM = 3
local MIN_ZOOM = 1
local ZOOM_TOGGLE_FACTOR = 0.5

---@param offset number
---@return nil
local function zoom(offset)
    local current = hl.get_config("cursor.zoom_factor")

    -- If no offset is provided, default to zoom after toggle, else use passed zoom value
    current = current + (offset and offset or ZOOM_TOGGLE_FACTOR)
    if current < MIN_ZOOM then current = MIN_ZOOM end
    if current > MAX_ZOOM then current = MAX_ZOOM end

    hl.config({ cursor = { zoom_factor = current } })
end

hl.bind("SUPER + Z", zoom)
hl.bind("SUPER + KP_ADD", function()
    zoom(0.5)
end)
hl.bind("SUPER + Minus", function()
    zoom(-0.5)
end)
```

### Launching programs on workspace creation

To replicate the behavior of the old `on_created_empty` workspace rule, use the `workspace.created` [event](../core/advanced-configuration/events) to launch programs.
For example:

```lua
local workspace_programs = {
    ["5"]               = { "firefox", { float = true } },
    ["6"]               = { "kitty",   { fullscreen = true } },
    ["special:special"] = { "discord", {} },
}

hl.on("workspace.created", function(ws)
    if not ws.is_empty then return end

    local program = workspace_programs[ws.addressable_name]
    if not program then return end

    local cmd, rules = table.unpack(program)

    -- Shallow-copy the rules table
    -- Without the copy, it would modify the original table in workspace_programs
    local shallow_rules = {}
    for k, v in pairs(rules) do shallow_rules[k] = v end
    shallow_rules.workspace = ws.addressable_name .. " silent"

    hl.exec_cmd(cmd, shallow_rules)
end)
```

### Move focus between tiled and floating windows

This functions similarly to the i3 `focus mode_toggle` bind.

```lua
hl.bind("SUPER + space", function()
    local window = hl.get_active_window()
    if not window then return end

    hl.dispatch(hl.dsp.window.cycle_next({
        floating = not window.floating,
        tiled = window.floating,
    }))
end, { description = "Switch focus between tiled and floating windows" })
```

### Pin floating windows with no_focus, and restore them

This function lets floating windows such as lyrics stay visible on every workspace, without stealing focus from other windows.
It also restores them to normal floating windows when you need to move them around.  
Note: calling the function again at a common window will restores all windows that were set to this state.

```lua
local function pin_nofocus_toggle()
    local tag = "pin_nofocus"

    local function has_tag(window)
        for _, t in ipairs(window.tags or {}) do
            if t == tag then
                return true
            end
        end
        return false
    end

    return function()
        local window = hl.get_active_window()
        if not window then return end

        if window.floating and window.fullscreen == 0 and not window.pinned and not has_tag(window) then
            -- Tag the window and mark it as pinned with no_focus
            hl.dispatch(hl.dsp.window.tag({ tag = "+" .. tag, window = window }))
            hl.dispatch(hl.dsp.window.pin({ window = window }))
            hl.dispatch(hl.dsp.window.set_prop({ prop = "no_focus", value = "1", window = window }))
        else
            -- Restore all windows that were marked this way
            for _, marked_window in ipairs(hl.get_windows({ tag = tag })) do
                hl.dispatch(hl.dsp.window.set_prop({ prop = "no_focus", value = "unset", window = marked_window }))
                if marked_window.pinned then
                    hl.dispatch(hl.dsp.window.pin({ window = marked_window }))
                end
                hl.dispatch(hl.dsp.window.tag({ tag = "-" .. tag, window = marked_window }))
            end
        end
    end
end
hl.bind("SUPER + P", pin_nofocus_toggle())
```

### Vim-like keymaps

Hyprland has so many features that you might run out of keys on your keyboard if you want to bind them all.
Rest assured, you can utilize submaps to create keymaps if you want more, and they're also easier to press than a single bind with many modifiers.

Here's an example of managing window groups this way:

```lua
hl.bind("SUPER + G", hl.dsp.submap("group_management"), { description = "Enter a group management submap" })

---@param keys string
---@param action HL.Dispatcher
---@param description string
---@return HL.Keybind
local map = function(key, action, description)
    hl.bind(key, function()
        hl.dispatch(action)
        hl.dispatch(hl.dsp.submap("reset"))
    end, { description = description })
end

hl.define_submap("group_management", function()
    map("G", hl.dsp.group.toggle(), "Toggle window group")

    map("H", hl.dsp.window.move({ into_group = "l" }), "Move window into a group on the left")
    map("J", hl.dsp.window.move({ into_group = "d" }), "Move window into a group on the bottom")
    map("K", hl.dsp.window.move({ into_group = "u" }), "Move window into a group on the top")
    map("L", hl.dsp.window.move({ into_group = "r" }), "Move window into a group on the right")

    map("E", hl.dsp.window.move({ out_of_group = true }), "Move window out of group")

    map("N", hl.dsp.group.next(), "Next window in group")
    map("P", hl.dsp.group.prev(), "Previous window in group")

    map("F", hl.dsp.group.move_window(), "Move window forward in the group order")
    map("B", hl.dsp.group.move_window({ forward = false }), "Move window backward in the group order")

    map("T", hl.dsp.group.lock_active(), "Toggle group lock")

    for i = 1, 10 do
        map(tostring(i % 10), hl.dsp.group.active({ index = i }), "Focus window " .. i .. " in a group")
    end

    hl.bind("Escape", hl.dsp.submap("reset"), { description = "Quit submap" })
end)
```

### Close All Windows At Once

```lua
local function closeAllWindows()
    local windows = hl.get_windows()

    for _,w in pairs(windows) do
        hl.dispatch(hl.dsp.window.close({ window = w }))
    end
end

local function closeAllWindowsCurrentWorkspace()
    local cws = hl.get_active_special_workspace() or hl.get_active_workspace()
    local windows = hl.get_windows({ workspace = cws })

    for _,w in pairs(windows) do
        hl.dispatch(hl.dsp.window.close({ window = w }))
    end
end

hl.bind("SUPER + BackSpace", closeAllWindowsCurrentWorkspace )
hl.bind("SUPER + Delete", closeAllWindows )
```

### Move All Windows In Current Workspace To Another

```lua
---@param ws HL.Workspace
---@param follow boolean
---@return nil
local function moveWindowsCurrentWorkspace(ws, follow)
    local cws = hl.get_active_special_workspace() or hl.get_active_workspace()
    local windows = hl.get_windows({ workspace = cws })

    for _, w in pairs(windows) do
        hl.dispatch(
            hl.dsp.window.move({
                window = w,
                workspace = ws,
                follow = follow
            })
        )
    end
end

for i = 1, 10 do
    local key = i % 10
    hl.bind("SUPER + SHIFT + ALT + " .. key, function()
        moveWindowsCurrentWorkspace(i, true)
    end)
end

for i = 1, 10 do
    local key = i % 10
    hl.bind("SUPER + CTRL + ALT + " .. key, function()
        moveWindowsCurrentWorkspace(i, false)
    end)
end
```

### Switch To Workspaces 01-99

```lua
hl.bind("SUPER + P", hl.dsp.submap("ws_tens"), { description = "Workspace picker (01-99)" })

hl.define_submap("ws_tens", function()
    for tens = 0, 9 do
        hl.bind(tostring(tens), hl.dsp.submap("ws_units_" .. tens))
    end

    local letters = "abcdefghijklmnopqrstuvwxyz"
    for i = 1, #letters do
        hl.bind(letters:sub(i, i), hl.dsp.submap("reset"))
    end
    hl.bind("Escape", hl.dsp.submap("reset"))
end)

for tens = 0, 9 do
    hl.define_submap("ws_units_" .. tens, "reset", function()
        for units = 0, 9 do
            local target = tens * 10 + units
            if target > 0 then
                hl.bind(tostring(units), hl.dsp.focus({ workspace = target }))
            end
        end
        hl.bind("Escape", hl.dsp.submap("reset"))
        hl.bind("catchall", hl.dsp.submap("reset"))
    end)
end
```
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 CodeCodexUnverifiedInstall
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