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/hypr-libraries.md

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

# Hypr Ecosystem Libraries Reference

---
weight: 50
title: Hypr Ecosystem
---

This wiki section hosts docs for various hypr\* projects.

> [!NOTE]
> These docs always target the latest _-git_ branch of the respective apps.

## Wiki Pages

Check out the wiki pages for each app, or their GitHub repo.

### User Apps and Utilities

- [hyprpaper](./user/hyprpaper) | [GitHub](https://github.com/hyprwm/hyprpaper)
- [hyprpicker](./user/hyprpicker) | [GitHub](https://github.com/hyprwm/hyprpicker)
- [hyprlauncher](./user/hyprlauncher) | [GitHub](https://github.com/hyprwm/hyprlauncher)
- [hypridle](./user/hypridle) | [GitHub](https://github.com/hyprwm/hypridle)
- [hyprlock](./user/hyprlock) | [GitHub](https://github.com/hyprwm/hyprlock)
- [xdg-desktop-portal-hyprland](./user/xdg-desktop-portal-hyprland) | [GitHub](https://github.com/hyprwm/xdg-desktop-portal-hyprland)
- [hyprsysteminfo](./user/hyprsysteminfo) | [GitHub](https://github.com/hyprwm/hyprsysteminfo)
- [hyprsunset](./user/hyprsunset) | [GitHub](https://github.com/hyprwm/hyprsunset)
- [hyprpolkitagent](./user/hyprpolkitagent) | [GitHub](https://github.com/hyprwm/hyprpolkitagent)
- [hyprland-qt-support](./user/hyprland-qt-support) | [GitHub](https://github.com/hyprwm/hyprland-qt-support)
- [hyprqt6engine](./user/hyprqt6engine) | [GitHub](https://github.com/hyprwm/hyprqt6engine)
- [hyprpwcenter](./user/hyprpwcenter) | [GitHub](https://github.com/hyprwm/hyprpwcenter)
- [hyprshutdown](./user/hyprshutdown) | [GitHub](https://github.com/hyprwm/hyprshutdown)
- [hyprtoolkit](./user/hyprtoolkit) | [GitHub](https://github.com/hyprwm/hyprtoolkit)
- [hyprcursor](./user/hyprcursor) | [GitHub](https://github.com/hyprwm/hyprcursor)

### Dev Libraries and Toolkits

- [hyprtoolkit](./dev/hyprtoolkit) | [GitHub](https://github.com/hyprwm/hyprtoolkit)
- [hyprutils](./dev/hyprutils) | [GitHub](https://github.com/hyprwm/hyprutils)
- [hyprlang](./dev/hyprlang) | [GitHub](https://github.com/hyprwm/hyprlang)
- [hyprwayland-scanner](./dev/hyprwayland-scanner) | [GitHub](https://github.com/hyprwm/hyprwayland-scanner)
- [aquamarine](./dev/aquamarine) | [GitHub](https://github.com/hyprwm/aquamarine)
- [hyprgraphics](./dev/hyprgraphics) | [GitHub](https://github.com/hyprwm/hyprgraphics)
- [hyprland-guiutils](./dev/hyprland-guiutils) | [GitHub](https://github.com/hyprwm/hyprland-guiutils)

---

---
weight: 140
title: hyprtoolkit (user docs)
---

[hyprtoolkit](https://github.com/hyprwm/hyprtoolkit) is a GUI toolkit for developing applications that run natively on Wayland.
It's specifically made for Hyprland's needs, but will generally run on any Wayland compositor that supports modern standards.

For developer documentation, see the [hyprtoolkit developer docs](../../dev/hyprtoolkit).

## Configuration

The general toolkit config is at `~/.config/hypr/hyprtoolkit.conf`.
It contains theming and some minor adjustments and supports the same color options as Hyprland.

| Variable | Description | Type | Default |
| --- | --- | --- | --- |
| `background` | Background color. | color | `0xFF181818` |
| `base` | Base color. | color | `0xFF202020` |
| `text` | Text color. | color | `0xFFDADADA` |
| `alternate_base` | Alternative base color. | color | `0xFF272727` |
| `bright_text` | Bright text color. | color | `0xFFFFDEDE` |
| `accent` | Accent color. | color | `0xFF00FFCC` |
| `accent_secondary` | Secondary accent color. | color | `0xFF0099F0` |
| `h1_size` | Font size for H1. | int | `19` |
| `h2_size` | Font size for H2. | int | `15` |
| `h3_size` | Font size for H3. | int | `13` |
| `font_size` | Font size for regular text elements. | int | `11` |
| `small_font_size` | Font size for small text elements. | int | `10` |
| `icon_theme` | Name of the icon theme to use, empty for "the first found". | string | [[Empty]] |
| `font_family` | Name of the font family to use. | string | `Sans Serif` |
| `font_family_monospace` | Name of the monospace font family to use. | string | `monospace` |
| `rounding_large` | Big rounding in logical px | int | `10` |
| `rounding_small` | Small rounding in logical px | int | `5` |

---

---
weight: 50
title: hyprtoolkit (developer docs)
---

Hyprtoolkit is a pure C++ toolkit.
It relies on modern C++ in the Hyprland style (with hyprutils, etc.).

It's recommended you are familiar with C++ before developing an app with hyprtoolkit.

For user documentation, see the [hyprtoolkit user docs](../../user/hyprtoolkit).

## Getting Started

_If you prefer living off of examples, see the `tests/` directory in the hyprtoolkit repo._

Start by creating a backend and opening a window:

```cpp
// in this example we are doing this to skip Hyprtoolkit::
using namespace Hyprtoolkit;

auto backend = CBackend::create();
auto window = CWindowBuilder::begin()->appTitle("Hello")->appClass("hyprtoolkit")->commence();
```

This will create (but not yet open) a window handle for you.

Hyprtoolkit is a retained mode toolkit, so you can define your layout with C++ and forget about it.

First thing we need is a background rectangle, by doing this:

```cpp
window->m_rootElement->addChild(CRectangleBuilder::begin()->color([] { return backend->getPalette()->m_colors.background; })->commence());
```

> [!NOTE]
> Remember to always use the palette when possible for your app to adhere to the user's theme.

All elements are under `hyprtoolkit/elements/`, you can browse through them.
Let's add a simple layout with some buttons:

```cpp
auto layout = CColumnLayoutBuilder::begin()->size({CDynamicSize::HT_SIZE_PERCENT, CDynamicSize::HT_SIZE_PERCENT, {1.F, 1.F}})->commence();
layout->setMargin(3);

window->m_rootElement->addChild(layout);

layout->addChild(CButtonBuilder::begin()
                       ->label("Do something")
                       ->onMainClick([](SP<CButtonElement> el) { std::println("Did something!"); })
                       ->size({CDynamicSize::HT_SIZE_AUTO, CDynamicSize::HT_SIZE_AUTO, {1, 1}})
                       ->commence()
                );
layout->addChild(CButtonBuilder::begin()
                       ->label("Do something else")
                       ->onMainClick([](SP<CButtonElement> el) { std::println("Did something else!"); })
                       ->size({CDynamicSize::HT_SIZE_AUTO, CDynamicSize::HT_SIZE_AUTO, {1, 1}})
                       ->commence()
                );
```

This adds a column layout (elements are stacked on top of each other) with two buttons.
These buttons have automatic sizing, so will fit their contents.

Once you are done, add a close callback, open the window and enter the main loop:

```cpp
window->m_events.closeRequest.listenStatic([w = WP<IWindow>{window}] {
    w->close();
    backend->destroy();
});

window->open();

backend->enterLoop();
```

## Layout System

The layout system relies on absolute and layout positioning modes. Let's zoom into both:

### Absolute Mode

This happens when the parent of your element is anything but a `ColumnLayout` or a `RowLayout`.
Children are positioned within their parent, according to their position mode.
You can set it with `setPositionMode` and add offsets with `setAbsolutePosition`.

For example:
- `setPositionMode` with `CENTER` will center the child inside the parent.
- `setPositionMode` with `ABSOLUTE` will make it be in the top left corner.
- Adding `setAbsolutePosition` to the above with `{200, 200}` will move it 200 layout px down and right from the top left corner of the parent.

### Layout Mode

This happens when the parent of your element is a layout.
These will attempt to position your child elements.
They work similarly to CSS's `flex` and Qt's `RowLayout` and `ColumnLayout`, but will not wrap.
If elements overflow and cannot shrink, they will disappear.

RowLayout positions elements next to each other side-by-side, while ColumnLayout does it top-to-bottom.

### Size

All elements carry a `SizeType`.
This tells the layout system how to size the element.
- `ABSOLUTE` takes layout px as size and makes the element rigid.
- `PERCENT` takes a percentage in the form of `(0, 0) - (1, 1)` and will be the size of the parent multiplied by the percentage.
- `AUTO` ignores the passed vector (leave it empty) and instead will always attempt to contain the children\*

> [!NOTE]
> Some elements will force their own sizing (e.g., `Text`).
> Leave them `AUTO` to avoid confusion.

## Elements

Most elements are self-explanatory.
You can explore their builder functions to see what styling/behavior options they support.

Each element is created with a `Builder` which is there to maintain ABI stability.
After you call `->commence()`, you will get a `SP` to the newly created object.

You can rebuild the object at any time by calling `->rebuild()` and you'll get a builder again.
**Remember to call `commence()` after you are done to apply the changes!**

You do not need to keep the `SP` after adding the element to the tree with `addChild`.

## Other

Other, miscellaneous stuff

### System Icons

Use the `CBackend::systemIcons()` function to obtain a reference to `ISystemIconFactory` which allows you to query system icons by name.
You can check the obtained result object to see if the icon was found.
Then, you can take that object and slap it into an `ImageElement` to add it to your layout.

### Additional FDs

If you have an app that depends on some other loop (e.g., PipeWire, D-Bus, etc.), you need to remember that hyprtoolkit is strictly single-threaded for layout and rendering.
You cannot edit the layout from another thread.

For this, use `CBackend::addFd()` to add a FD to the loop alongside a function that will be called once the fd is readable.
This function will be called from the main thread, so you can do whatever you want in there.

---

---
weight: 40
title: hyprlang
---

[hyprlang](https://github.com/hyprwm/hyprlang) is a library that implements parsing for the hypr configuration language.

## Syntax

### Line Style

Every config line is a command followed by a value.

```ini
COMMAND = VALUE
```

The command can be a variable, or a special keyword (those are defined by the app you are using).

Variables are like "options", while keywords are like "commands".
Options can be specified only once (if you do it more times, the previous one will be overwritten), while commands invoke some behavior every time they are defined.

The trailing spaces at the beginning and end of words are not necessary, and are there only for legibility.

### Categories

Categories can be regular or "special".

Both are specified in the same way:

```ini
category {
    variable = value
}
```

Special categories can have other properties, like for example containing a key:

```ini
special {
    key = A
    variable = value
}
special {
    key = B
    variable = value
}
```

This is like defining two "groups", one with the key of A, another with B.
Hyprland for example uses those for per-device configs.

### Defining variables

Variables can be defined like so:

```ini
$VAR = myData
```

Later on, you can use them like so:

```ini
$SUFFIX = -san
$NAME = Jeremy
greeting = Hello, $NAME$SUFFIX.
```

> [!NOTE]
> Spaces around or separating values are not mandatory.

### Comments

Comments are started with the `#` character.

If you want to escape it (put an actual `#` and not start a comment) you can use `##`.
It will be turned into a single `#` that _will_ be a part of your line.

### Escaping Errors

If you use plugins, you may want to ignore errors from missing options/keywords so that you don't get an error bar before they are loaded.
To do so, do this:

```ini
# hyprlang noerror true

bind = MOD, KEY, something, amogus
someoption = blah

# hyprlang noerror false
```

### Inline Options

If you want to specify an option inline, without opening and closing a category, use the `:` separator:

```ini
category:variable = value
```

If the category is special and requires a key, you can write:

```ini
category[keyvalue]:variable = value
```

This is the syntax used by `hyprctl keyword`, for example.

### Arithmetic Operations

Since 0.6.3, hyprlang supports _very_ basic arithmetic operations on variables using `{{}}`

You can use `+`, `-`, `*`, or `/`, on only _two_ variables (or constants) at a time.
You _cannot_ nest them, but you can use intermittent variables.

Example:
```ini
$VAR1 = 2
$VAR2 = {{VAR1 + 3}}
$VAR3 = {{VAR2 * 2}}

someVariable = {{VAR3 / 2}}
someVariable2 = VAR3
```

This may throw some errors if done incorrectly.
Make sure that:
- You only have two sides to the operation (**NOT** `{{a + b + c}}`, that has three)
- Both sides either exist as numeric variables or are numeric themselves
- You have spaces around the operator (**NOT** `{{a+b}}`)

### Arithmetic Escaping

Since 0.6.4, hyprlang allows for escaping arithmetic expressions, e.g.`{{a + b}}`, by prefixing a `\`.
They can be used on any of the starting positions of the expression braces.

Example:
```ini
$VAR = \{{10 + 10}}
bind = MOD, KEY, exec, COMMAND "{\{10 + 10}}"
someVariable = \{\{10 + 10}}
```

This will not evaluate the expression, and instead just assign the raw value you wrote verbatim.
All of the `\` that were used to escape will be removed from the value as well.
So `\{{hello world}}` will turn into `{{hello world}}`, without trying to parse it as an expression.

### Escaping Escapes

Since 0.6.4, you can escape any `\` that would have been used to escape other characters.

For example, if you want to have a `\` before a real expression:

```ini
someVariable = \\{{VAR1 + 10}}
```

If you want to have an `\` before any of the escapable characters:

```ini
someOtherVariable = \\{ hello \\}
```

### Conditionals

Since 0.6.4, you can add conditionals to your configs.
You can make blocks conditional by using the `# hyprlang if` directive.

Some examples:

```ini
# hyprlang if MY_VAR

test = 24

# hyprlang endif

# hyprlang if !MY_VAR

test = 12

# hyprlang endif
```

> [!NOTE] Some important information
> - A variable is `true` if and only if it exists and is not an empty string.
> - Environment variables are supported.
> - Dynamic keywords (with `hyprctl keyword`) will **NOT** re-trigger or un-trigger these blocks.
>   Changes need to be made to the files directly (or environment) and in the case of the latter, or a hypr\* app that doesn't automatically reload its config, a relaunch of the app/`hyprctl reload` (for hl) will be required.

## Developer Documentation

See the documentation at [standards.hyprland.org/hyprlang](https://standards.hyprland.org/hyprlang/).

---

---
weight: 60
title: hyprutils
---

[hyprutils](https://github.com/hyprwm/hyprutils) is a library providing shared implementations of commonly used types across the hypr\* ecosystem.

---

---
weight: 20
title: hyprgraphics
---

[hyprgraphics](https://github.com/hyprwm/hyprgraphics) is a library providing shared implementations of some utilities relating to graphics and resources, like loading images or color calculations.

---

---
weight: 10
title: aquamarine
---

[aquamarine](https://github.com/hyprwm/aquamarine) is a very light Linux rendering backend library.

It is not a replacement or competitor to any other Wayland compositor library (e.g., wlroots, libweston).
Instead it implements only the low-level KMS, DRM, etc. rendering backends.

## Configuration

Configuration options are passed via environment variables starting with `AQ_` to an app that uses aquamarine (e.g., Hyprland).

### Variables
Environment variables for configuring Aquamarine are listed at [the environment variables page.](../../../configuring/core/environment-variables/)

---

---
weight: 70
title: hyprwayland-scanner
---

[hyprwayland-scanner](https://github.com/hyprwm/hyprwayland-scanner), also called hw-s, is a utility to generate sources and headers for Wayland protocol specifications.

It is similar to wayland-scanner, but instead of C, it generates neat and safe C++ implementations.

---

---
weight: 30
title: hyprland-guiutils
---

[Hyprland GUI utilities](https://github.com/hyprwm/hyprland-guiutils) is a successor to hyprland-qtutils.

---

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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated 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: 323kUpdated Claude CodeCodexVerifiedInstall