marceloeatworld/hyprland-ai-skill
hyprland
FlaggedThis 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.
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
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Unverified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |