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/lua-scripting.md

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

# Hyprland Lua Scripting: Events and Utilities

---
weight: 100
title: Advanced configuration
---

This section is for advanced things.
Here you can find info on how to interact with Hyprland's Lua API.

Read more about it in the following pages:
{{< subpage_list >}}

---

---
weight: 10
title: Lua events
---

## Events

With `hl.on`, you can define callbacks on events.
You can register as many as you want.

```lua
hl.on("window.active", function(w)
  hl.notification.create({ text = "Window focused: " .. w.title, timeout = 5000, icon = "ok" })
end)
```

Or, if you're working with events that have multiple parameters:

```lua
hl.on("workspace.move_to_monitor", function(ws, m)
  hl.notification.create({
    text = "Workspace: " .. ws.name .. " moved to a monitor at x: " .. m.position.x,
    timeout = 4000,
    icon = "ok"
  })
end)
```

Event list:

| Event | Description | Parameters |
| --- | --- | --- |
| config.props_refreshed | Emitted when a prop refresh event is executed | bool: `true` if the [prop refresh](../lua-utilities/#prop-refresh) event is being executed as scheduled, `false` if executed prematurely with the Lua function |
| config.reloaded | Emitted when the config has been reloaded **and applied** | None |
| config.unload | Emitted just before the config is unloaded and Lua state torn down, i.e. on reload or shutdown, to close or save things before they are lost | None |
| hyprland.shutdown | Emitted once before Hyprland exits | None |
| hyprland.start | Emitted once on start | None |
| input.keyboard.key | Emitted when a key is pressed or released | integer: XKB keycode; integer: Unix timestamp that the event occurred; integer: released (0), pressed (1), or repeated (2) |
| keybinds.submap | Emitted when the active submap changes. An empty string means the default submap was restored | string: Submap Name |
| layer.closed | Emitted when a layer surface is closed | LayerSurface |
| layer.opened | Emitted when a layer surface is opened | LayerSurface |
| monitor.added | Emitted when a monitor is connected and ready | Monitor |
| monitor.focused | Emitted when the active monitor changes | Monitor |
| monitor.layout_changed | Emitted when the monitor arrangement changes. This occurs when a monitor is added or removed, a monitor's resolution or refresh rate is changed, or the config is reloaded with different rules | None |
| monitor.removed | Emitted when a monitor is disconnected and removed | Monitor |
| screenshare.state | Emitted when a screenshare session starts or stops | Bool: Active, Integer: Type, String: Name |
| window.active | Emitted when the active window changes | Window; int (focus reason) |
| window.bell | Emitted when a window rings the system bell, even if it's muted | Window |
| window.class | Emitted when a window class changes | Window |
| window.close | Emitted when a window is closed. It may still be visible during its closing animation | Window |
| window.destroy | Emitted when a window is removed from the compositor. For windows with a close animation, fires after the animation completes | Window |
| window.fullscreen | Emitted when the fullscreen status of a window changes | Window |
| window.kill | Emitted when a window is forcefully killed via hyprctl kill | Window |
| window.minimize | Emitted when a window requests to change its minimized state | Window; bool: `true` if requesting minimization, `false` for unminimization |
| window.move_to_workspace | Emitted when a window is moved to a different workspace | Window; Workspace |
| window.open | Emitted when a window is fully initialized with window rules applied | Window |
| window.open_early | Emitted when a window is created and mapped, but **before** window rules are applied | Window |
| window.pin | Emitted when a window is pinned or unpinned | Window |
| window.title | Emitted when a window title changes | Window |
| window.update_rules | Emitted when a window's rules are re-evaluated, e.g. when its title or class changes | Window |
| window.urgent | Emitted when a window requests an `urgent` state | Window |
| window.update_state | Emitted when a window's desktop state changes. State table has flags (e.g. `pinned` or `floating`). Nil means unchanged. | Window, State table |
| workspace.active | Emitted when the active workspace on a monitor changes | Workspace |
| workspace.created | Emitted when a workspace is created, after activating if appropriate | Workspace |
| workspace.created_early | Emitted when a workspace is created, but **before** it is activated | Workspace |
| workspace.move_to_monitor | Emitted when a workspace is moved to a different monitor | Workspace; Monitor |
| workspace.removed | Emitted when a workspace is removed | Workspace |
| workspace.special_active | Emitted when the opened special workspace on a monitor changes. Workspace of nil means no special workspace is open | Workspace; Monitor |

---

---
weight: 10
title: Lua utilities
---

## Lua utilities

Hyprland exposes a bunch of Lua utilities for you to script your desktop with custom functionality and more.

{{% details title="Example" closed="true" %}}
```lua
-- bind to toggle floating, unless the window is htop,
-- then only set floating

hl.bind("SUPER + X", function()
  local w = hl.get_active_window()
  if w ~= nil and w.title == "htop" do
    hl.dispatch(hl.dsp.window.float({ action = "set" }))
  else
    hl.dispatch(hl.dsp.window.float({ action = "toggle" }))
  end
end)
```
{{% /details %}}

### Convenience functions

Hyprland exposes the following convenience functions:
- `hl.get_config()`
- `hl.get_active_window()`
- `hl.get_windows()`
- `hl.get_window(selector)`
- `hl.get_urgent_window()`
- `hl.get_workspaces()`
- `hl.get_workspace(selector)`
- `hl.get_active_workspace()`
- `hl.get_active_special_workspace()`
- `hl.get_monitors({ all? })`
- `hl.get_monitor(selector)`
- `hl.get_active_monitor()`
- `hl.get_monitor_at({ x = int, y = int })`
- `hl.get_monitor_at_cursor()`
- `hl.get_cursor_pos()`
- `hl.get_last_window()`
- `hl.get_last_workspace()`
- `hl.get_layers()`
- `hl.get_workspace_windows(workspace_selector)`
- `hl.get_current_submap()`
- `hl.version()`
- `hl.exec_cmd()`
- `hl.exec_scheduled_prop_refresh_immediately()`
- `hl.get_loaded_plugins()`
- `hl.is_key_down(key = int/string)`

Use the LSP (or examine the stubs yourself) for the return values (classes and their parameters) of these functions.
See [here](../../../core#editor-autocompletion) to set up the LSP in your code editor.

### `hl.exec_cmd` function

`hl.exec_cmd()` will spawn an asynchronous process, so there is no need for `& disown` at the end.

### Dynamically changing a config option:

You can use `hl.get_config()` to get the current value of a config option.
Pass a config option like `"general.layout"`.

Pay attention that the return type of `hl.get_config()` will be a representation of the actual underlying type.

For example, if your `general.gaps_in` is set as `gaps_in = 3` in `hl.config()`, `hl.get_config()` returns a table of the form:
```lua
{
  top = 3,
  left = 3,
  right = 3,
  bottom = 3
}
```
because `gaps_in` also accepts a table of the form `{ top?, left?, right?, bottom? }`.

You can change the value of a config option via a keybind, with a script like:
```lua
-- Toggle gaps_in between 0 and 3 (equivalent to  {3, 3, 3, 3} )
hl.bind(mainMod .. " + SHIFT + G", function()
    if hl.get_config("general.gaps_in").top == 3 then
        hl.config({ ["general.gaps_in"] = 0 })
    else
        hl.config({ ["general.gaps_in"] = 3 })
    end
end)
```

### Prop Refresh

A prop refresh is an event where Hyprland updates/refreshes many of its configurable options (e.g., keyboard layouts, device configurations, monitor states, window gaps, etc.).

Events such as the creation of a workspace rule cause a prop refresh event to be scheduled after the current event.

Hyprland schedules a **single** prop refresh event to be executed at the end of the current event (e.g., a Lua function) in order to avoid redundant prop refreshes.

In practice, this means that when you create a new workspace rule that removes `gaps_in` from the current workspace, the value for `gaps_in` is only changed at the end of your Lua function, and subsequent lines of code within your Lua function after setting the workspace rule don't use the updated value; only after the end of your Lua function does the `gaps_in` value of your current workspace get updated to reflect the new workspace rule.

This might cause problems if you expect the `gaps_in` value of your workspace to be immediately updated after the workspace rule is created.

To execute a scheduled prop refresh immediately, use `hl.exec_scheduled_prop_refresh_immediately()`.
Note that because the scheduled event is executed prematurely, it is removed from the event loop; allowing another prop refresh to be enqueued.

> [!WARNING]
> Overuse of this function may cause slowdowns!
> Use `config.props_refreshed` event to see how many prop refreshes are fired per event.

### Timers

You can spawn and manage timers via `hl.timer()`:

```lua
local demoTimer = hl.timer(function()
  print("hello from timer")
end, { timeout = 1000, type = "repeat" })

demoTimer:set_enabled(false)

hl.bind("SUPER + X", function()
  -- toggle the timer
  demoTimer:set_enabled(not demoTimer:is_enabled())
end)
```

## Sockets (IPC)

It's recommended to use Lua in most cases.
Lua is faster, less error-prone, has more features, and is generally more integrated.
However, if you want to use IPC instead, check the [IPC](../../../../ipc) page.

---

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