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/window-rules.md
View on GitHub<!-- source: https://wiki.hypr.land/configuring/core/rules -->
<!-- wiki commit: 41c7222 (2026-11-20 18:16:21 +0100) -->
<!-- auto-generated by scripts/generate-references.sh - DO NOT EDIT MANUALLY -->
# Hyprland Window and Layer Rules Reference
---
weight: 60
title: Rules
---
Rules can be used to enforce specific options for matched windows/workspaces/layers.
Rules can be either named or anonymous.
Rules are split into two categories of parameters: _props_ and _effects_.
Props are the fields inside the `match` table, which are used to determine if a window should get the rule.
Effects are the other fields outside of `match`, and change the behavior of the targeted window.
Rules are evaluated top to bottom, but all named rules are evaluated first, then all anonymous ones.
_All_ props must match for a rule to be applied.
You can have as many props and effects per rule as you want, and in any order.
Note that the `match` table cannot be empty, however.
In the output of the `hyprctl clients` command, `fullscreen` refers to `fullscreen_state_internal`, and `fullscreenClient` refers to `fullscreen_state_client`.
Read more about rules in the following pages:
{{< subpage_list >}}
---
---
weight: 10
title: Window Rules
---
## Syntax
```lua
hl.window_rule({
name? = string,
match = {
prop = some_prop_value,
},
effect = some_effect_value,
})
```
## Window Rules
You can set window rules to achieve different window behaviors based on their properties.
### Props
The supported fields for the `match` table are:
| Prop | Description | Type |
| --- | --- | --- |
| class | Windows with `class` matching `RegEx` | [RegEx] |
| content | Windows with specified content type (none, photo, video, game) | string |
| focus | Currently focused window | bool |
| fullscreen | Fullscreen (covering or non-covering) windows | bool |
| fullscreen_state_client | Windows with matching `fullscreenstate`. `0` - none, `1` - maximize, `2` - fullscreen, `3` - maximize and fullscreen | int |
| fullscreen_state_internal | Windows with matching `fullscreenstate`. `0` - none, `1` - maximize, `2` - fullscreen, `3` - maximize and fullscreen | int |
| float | Floating windows | bool |
| group | Grouped windows | bool |
| initial_class | Windows with `initialClass` matching `RegEx` | [RegEx] |
| initial_title | Windows with `initialTitle` matching `RegEx` | [RegEx] |
| modal | Modal windows (e.g., "Are you sure" popups) | bool |
| pin | Pins the window (i.e. show it on all workspaces). **Important: pinning is ignored for non-floating windows** | bool |
| tag | Windows with matching `tag` | string |
| title | Windows with `title` matching `RegEx` | [RegEx] |
| workspace | Windows on matching workspace | workspace selector |
| xdg_tag | Match a window by its xdgTag | [RegEx] |
| xwayland | Xwayland windows | bool |
## Effects
### Static effects
> [!WARNING]
> It is not possible to `float` (or any other static rule) a window based on a change in the `title` after the window has been created.
> This applies to all static effects listed here.
>
> Instead, use a [dispatch](../../dispatchers) triggered by an [event](../../advanced-configuration/events) listener to apply the effect after the window has been created:
> ```lua
> hl.on("window.title", function(w)
> if w ~= nil and w.title == "foo" then
> hl.dispatch(hl.dsp.window.float({ action = "set" }))
> end
> end)
> ```
Static effects are evaluated once when the window is opened and never again.
This essentially means that it is always the `initialTitle` and `initialClass` which will be found when matching on `title` and `class`, respectively.
| Effect | Description | Type |
| --- | --- | --- |
| center | If the window is floating, will center it on the monitor | bool |
| content | Sets content type: `"none"`, `"photo"`, `"video"`, or `"game"` | string |
| float | Floats a window | bool |
| fullscreen | Fullscreens a window | bool |
| fullscreen_state | Sets the fullscreen mode for the internal client (e.g., `"1 2"`). Values: `0` none, `1` maximize, `2` fullscreen, `3` maximize and fullscreen | string |
| group | Sets window group properties. See [group options](#group-window-rule-options) below | string |
| maximize | Maximizes a window | bool |
| monitor | Sets the monitor on which a window should open (e.g., `"1"`, `"DP-1"`). Can be suffixed with `" silent"` | string |
| move | Moves a floating window to the given monitor-local coordinates. See [position and size](#position-and-size) below | table or string |
| no_close_for | Makes the window uncloseable with `killactive` for a given number of ms on open | int |
| no_initial_focus | Disables the initial focus to the window | bool |
| pin | Pins the window (i.e. show it on all workspaces). _Note: pinning is ignored for non-floating windows. You most likely want to use this together with `float = true`_ | bool |
| pseudo | Pseudotiles a window | bool |
| scrolling_width | Set column width for window when starting on a workspace with the scrolling layout | float |
| size | Resizes a floating window. See [position and size](#position-and-size) below | table or string |
| suppress_event | Ignores specific events. Space-separated: `"fullscreen"`, `"maximize"`, `"activate"`, `"activatefocus"`, `"fullscreenoutput"`, `"x11configurerequest"` | string |
| tile | Tiles a window | bool |
| workspace | Sets the workspace on which a window should open. Can also be `"unset"` or suffixed with `" silent"` | string |
#### Position and size
<!-- TODO: Table arguments should be { x = int, y = int }, https://github.com/hyprwm/Hyprland/discussions/16339. When (I hope it is "when", and not "if") this is fixed, section below should be edited to mention the correct form -->
Position and size arguments take a Lua table or a string.
Value can be a number or an [expression](#expressions).
The string argument is split at the first whitespace.
A single value, a table without exactly two elements, and any separator other than a whitespace, e.g.:`"800,600"`, `"800x600"`, are config errors.
##### Expressions
Expressions are simple shortcodes for basic information.
All position variables are monitor-local.
To be correctly parsed in a string argument, they should not contain spaces.
- `monitor_w` and `monitor_h` for monitor size
- `window_x` and `window_y` for window position
- `window_w` and `window_h` for window size
- `cursor_x` and `cursor_y` for cursor position
{{% details title="Examples" closed="true" %}}
```lua
-- Set size to x = 800, y = 600
size = { 800, 600 }
-- Same size, but via string
size = "800 600"
-- Move window center to the cursor position
move = { "cursor_x - (window_w * 0.5)", "cursor_y - (window_h * 0.5)" }
-- Align window with the left monitor border and 17 pixels below monitor center
move = { "window_w * 0.5", "(monitor_h / 2) + 17" }
-- Set windiw suze to the half monitor resolution
size = { "monitor_w * 0.5", "monitor_h * 0.5" }
-- Set max_size as half of the monitor width and height
max_size = "monitor_w*0.5 monitor_h*0.5"
```
{{% /details %}}
### Dynamic effects
Dynamic effects are re-evaluated every time a property changes.
<!-- SORT: opaque and force_rgbx are together because they do very similar -->
| Effect | Description | Argument | Limits |
| --- | --- | --- | --- |
| allows_input | Forces an Xwayland window to receive input even if it requests not to | bool | |
| animation | Forces an animation onto a window with an optional style (e.g., `"popin"`, `"popin 80%"`) | string | |
| border_color | Sets the window's border to a color or gradient. See [border_color](#border_color-window-rule) below | gradient | |
| border_size | Sets the border size | int | |
| confine_pointer | Locks the mouse cursor to the window. Mostly useful for keeping your mouse cursor locked to one monitor during gaming | bool | |
| dim_around | Dims everything around the window. Meant for floating windows | bool | |
| decorate | Whether to draw window decorations. (default: `true`) | bool | |
| focus_on_activate | Whether Hyprland should focus an app that requests to be focused | bool | |
| idle_inhibit | Sets an idle inhibit rule. Modes: `"none"`, `"always"`, `"focus"`, `"fullscreen"` | string | |
| immediate | Forces the window to allow tearing | bool | |
| keep_aspect_ratio | Forces aspect ratio when resizing with the mouse | bool | |
| max_size | Sets the maximum size for floating windows. See [position and size](#position-and-size) above | table or string | |
| min_size | Sets the minimum size for floating windows. See [position and size](#position-and-size) above | table or string | |
| nearest_neighbor | Forces nearest-neighbor filtering | bool | |
| no_anim | Disables animations for the window | bool | |
| no_auto_hdr | Disables AutoHDR for the window. This is useful to stop programs like `foot` triggering AutoHDR when they are fullscreened | bool | |
| no_blur | Disables blur for the window | bool | |
| no_dim | Disables window dimming for the window | bool | |
| no_focus | Disables focus to the window | bool | |
| no_follow_mouse | Prevents the window from being focused when the mouse moves over it when `input.follow_mouse=1` is set | bool | |
| no_glow | Disables glow for the window | bool | |
| no_max_size | Removes max size limitations | bool | |
| no_screen_share | Hides the window and its popups from screen sharing by drawing black rectangles in their place | bool | |
| no_shadow | Disables shadows for the window | bool | |
| no_shortcuts_inhibit | Disallows the app from inhibiting your shortcuts | bool | |
| no_vrr | Disables VRR for the window. Only works when `misc.vrr` is set to `2` or `3` | bool | |
| no_wobble | Disables wobble for the window | bool | |
| no_xdg_drags | If true, will disable XDG-driven drags for the window (e.g., dragging a CSD top bar) | bool | |
| opacity | Additional opacity multiplier (e.g., `"0.8"` overall, `"0.9 0.7"` active/inactive, `"1.0 0.8 0.9"` active/inactive/fullscreen). Append `" override"` after each value to set absolute instead of multiplied | string | |
| opaque | Set `decoration.active/inactive/fullscreen_opacity` to `1` for this window | bool | |
| force_rgbx | Disables the window's own transparency *(not Hyprland's given transparency, in contrast to the opaque rule)* | bool | |
| persistent_size | For floating windows, internally store their size. When a new floating window opens with the same class and title, restore the saved size | bool | |
| render_unfocused | Forces the window to think it's being rendered when it's not visible | bool | |
| rounding | Forces X pixels of rounding, ignoring the default | int | |
| rounding_power | Overrides the rounding power for the window | float | |
| scroll_mouse | Forces the window to override `input.scroll_factor` | float | |
| scroll_touchpad | Forces the window to override `input.touchpad.scroll_factor` | float | |
| stay_focused | Forces focus on the window as long as it's visible | bool | |
| sync_fullscreen | Whether the fullscreen mode should always be the same as the one sent to the window | bool | |
| tag | Applies a tag. Use prefix `+`/`-` to set/unset, or no prefix to toggle (e.g., `"+myTag"`) | string | |
| tonemap | Tonemapping behavior: `on` (Default), `off` disables tonemapping, `clamp` clamps source luminance to target, `limited` uses a dynamic curve to tonemap only the top end out of bounds content | string | |
| xray | Sets blur xray mode for the window | bool | |
All dynamic effects can be set with [`set_prop()`](../../dispatchers#set_prop).
### `group` window rule options
The `group` effect takes a string with space-separated options:
- `"barred"` - Do not automatically group into the focused unlocked group.
- `"deny"` - Do not allow the window to be toggled as or added to a group.
- `"invade"` - Force open window in the locked group.
- `"lock"` [`"always"`] - Lock the group. Combine with `"set"` or `"new"`.
- `"new"` - Shorthand for `"barred set"`.
- `"override"` [other options] - Override other `group` rules.
- `"set"` [`"always"`] - Open window as a group.
- `"unset"` - Clear all `group` rules.
> [!NOTE]
> `group` with no options is a shorthand for `group = "set"`.
>
> By default, `set` and `lock` only affect new windows once.
> The `always` qualifier makes them always effective.
### `border_color` window rule
The `border_color` rule accepts a single color or a gradient:
```lua
-- Single color
border_color = "rgb(FF0000)"
-- Gradient
border_color = { colors = { "rgba(33ccffee)", "rgba(00ff99ee)" }, angle = 45 }
```
The `border_color` rule can also be used in conjunction with the `focus` prop in order to independently set the active or inactive border color of a window.
For example:
```lua
-- Set Firefox's inactive border color to a gradient from magenta to cyan
hl.window_rule(
match = { class = "firefox", focus = false },
border_color = { colors = { "rgba(ffff00ee)", "rgba(00ffffee)" }, angle = 33 }
)
```
> [!TIP]
> Combine two rules, one with `focus = true` and another with `focus = false`, to set the active and inactive border colors of specific windows
> (similarly to how `general.col.active_border` and `general.col.inactive_border` affect windows normally).
### Tags
Window tags can be static or dynamic.
Dynamic tags have a suffix of `*`.
Check window tags with `hyprctl clients`.
To add a static tag, use `hl.dsp.window.tag` dispatcher.
To add a dynamic tag, use `tag` window rule.
The `tag` rule can only manipulate dynamic tags, and the `hl.dsp.window.tag` only works with static tags (dynamic tags are cleared when the dispatcher is called).
{{% details title="Examples" closed="true" %}}
```bash
hyprctl dispatch 'hl.dsp.window.tag({ tag = "+code" })' # Add tag to current window.
hyprctl dispatch 'hl.dsp.window.tag({ tag = "-code" })' # Remove tag from current window.
hyprctl dispatch 'hl.dsp.window.tag({ tag = "code" })' # Toggle the tag of current window.
# Or target windows
hyprctl dispatch 'hl.dsp.window.tag({ tag = "+music", window = "class:Celluloid" })'
```
```lua
-- Move kitty to 100 100 and add an anim style (named rule)
hl.window_rule({
name = "move-kitty",
match = { class = "kitty" },
move = {100, 100},
animation = "popin",
})
-- Disable blur for firefox
hl.window_rule({ match = { class = "firefox" }, no_blur = true })
-- Move kitty to the center of the cursor
hl.window_rule({
match = { class = "kitty" },
move = {"cursor_x-(window_w*0.5)", "cursor_y-(window_h*0.5)"},
})
-- Set border color to red if window is fullscreen
hl.window_rule({
match = { fullscreen = true },
border_color = "rgb(FF0000) rgb(880808)",
})
-- Set border color to yellow when title contains Hyprland
hl.window_rule({
match = { title = ".*Hyprland.*" },
border_color = "rgb(FFFF00)",
})
-- Set opacity to 1.0 active, 0.5 inactive and 0.8 fullscreen for kitty
hl.window_rule({
match = { class = "kitty" },
opacity = "1.0 override 0.5 override 0.8 override",
})
-- Set rounding to 10 for kitty
hl.window_rule({ match = { class = "kitty" }, rounding = 10 })
-- Fix pinentry losing focus
hl.window_rule({
match = { class = "(pinentry-)(.*)" },
stay_focused = true,
})
hl.window_rule({ match = { class = "footclient" }, tag = "+term" }) -- Add dynamic tag `term*`
hl.window_rule({ match = { class = "footclient" }, tag = "term" }) -- Toggle dynamic tag `term*`
hl.window_rule({ match = { tag = "cpp" }, tag = "+code" }) -- Add `code*` to windows tagged `cpp`
hl.window_rule({ match = { tag = "code" }, opacity = "0.8" }) -- Set opacity for tag `code` or `code*`
hl.window_rule({ match = { tag = "cpp" }, opacity = "0.7" }) -- `cpp`-tagged windows match both; last wins
hl.window_rule({ match = { tag = "term*" }, opacity = "0.6" }) -- Match `term*` only, not bare `term`
hl.window_rule({ match = { tag = "term" }, tag = "-code" }) -- Remove dynamic tag `code*` from `term`/`term*`
-- Or with a keybind
hl.bind("SUPER + CTRL + 2", hl.dsp.window.tag({ tag = "alpha_0.2" }))
hl.bind("SUPER + CTRL + 4", hl.dsp.window.tag({ tag = "alpha_0.4" }))
hl.window_rule({ match = { tag = "alpha_0.2" }, opacity = "0.2 override" })
hl.window_rule({ match = { tag = "alpha_0.4" }, opacity = "0.4 override" })
```
{{% /details %}}
### Notes
Effects marked as _dynamic_ are re-evaluated whenever the matching property of the window changes.
For instance, if a rule changes the `border_color` when a window is floating, the color reverts to default when it's tiled again.
Effects are processed top to bottom, and the _last_ match takes precedence.
Here, all non-fullscreen kitty windows have `opacity 0.8`, except when floating --- those get `0.5`.
All other floating windows get `0.5`.
```lua
hl.window_rule({ match = { float = true }, opacity = "0.5 override 0.5 override" })
hl.window_rule({ match = { class = "kitty" }, opacity = "0.8 override 0.8 override" })
```
### Dynamically enabling / disabling / changing rules
Only named rules can be dynamically changed, enabled, or disabled.
`hl.window_rule()` returns a handle object:
```lua
local myRule = hl.window_rule({
name = "my-rule",
match = { class = "kitty" },
border_size = 5,
})
myRule:set_enabled(false) -- disable
myRule:set_enabled(true) -- re-enable
myRule:is_enabled() -- query status
```
---
---
weight: 30
title: Layer rules
---
## Syntax
```lua
hl.layer_rule({
name? = string,
match = {
prop = some_prop_value,
},
effect = some_effect_value,
})
```
## Layer Rules
Some things in Wayland are not windows, but layers --- app launchers, status bars, wallpapers, etc.
These have separate rules using `hl.layer_rule()`.
The syntax is the same as `hl.window_rule()`.
### Props
| Prop | Description | Type |
| --- | --- | --- |
| namespace | Namespace of the layer. Check `hyprctl layers` | [RegEx] |
### Effects
> [!NOTE]
> If blur doesn't work in certain layers when enabled, it might be controlled by the client settings. See [FAQ](../../../../faq/#blur).
| Effect | Description | Type | Limits |
| ---- | --- | --- | --- |
| above_lock | If non-zero, renders the layer above the lock screen. `2` = interactive on lock screen | int | |
| animation | Sets a specific animation style for this layer | string | |
| blur | Enables blur for the layer | bool | |
| blur_popups | Enables blur for popups | bool | |
| dim_around | Dims everything behind the layer | bool | |
| ignore_alpha | Makes blur ignore pixels with an opacity equal or lower to this | float | [0.0 - 1.0] |
| no_anim | Disables animations | bool | |
| no_screen_share | Hides the layer from screen sharing | bool | |
| order | Sets the space-reservation order relative to other layers. A higher order layer takes priority when trying to reserve space over other lower order layers. Can be negative | int | |
| xray | Sets the blur xray mode for the layer | bool | |
{{% details title="Examples" closed="true" %}}
```lua
-- Enable blur for Waybar
hl.layer_rule({ match = { namespace = "waybar" }, blur = true })
-- Named layer rule
local selectionRule = hl.layer_rule({
name = "no-anim-for-selection",
match = { namespace = "selection" },
no_anim = true,
})
-- Enable blur and ignore_alpha for Rofi
hl.layer_rule({
match = { namespace = "rofi" },
blur = true,
ignore_alpha = 0.5,
})
```
{{% /details %}}
Layer rules also return a handle with `set_enabled()`/`is_enabled()`:
```lua
local myLayerRule = hl.layer_rule({
name = "my-layer-rule",
match = { namespace = "waybar" },
blur = true,
})
myLayerRule:set_enabled(false)
```
---
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 | Verified | 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 |