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/contributing.md

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

# Contributing and Debugging

---
weight: 140
title: Contributing and debugging
---

<!-- TODO:
If someone sees this todo and knows how to write that in a better way: be my guest :/
Also idk where to place it, so i just slapped it here
-->

> [!IMPORTANT]
> Please use English for all communications!
> This helps developers and other community members understand and participate.
> Content in any other language may be closed or ignored!
>
> Thanks for understanding.

PR, code styling and code FAQs are [here](./pr-guidelines).

For issues, please see [the guidelines](https://github.com/hyprwm/Hyprland/blob/main/docs/ISSUE_GUIDELINES.md).

## Getting Vouched

Before you submit a PR, you need to be vouched, or your PR will be closed automatically.

Please make a vouch request over [here](https://github.com/hyprwm/.github/discussions) if you wish to do so.

### Exemptions

PRs made for i18n (localisation) purposes are exempt from the vouch requirement.
Please read the comment on top of the PR body when making your PR for instructions for how to make such a PR.

## Build in debug mode

### Required packages

See [manual build](../getting-started/installation#manual-build) for deps.

### Clone the repository

Submodules must be included when cloning the repo: `git clone --recurse-submodules https://github.com/hyprwm/Hyprland.git`

### Building

#### VSCode

Install the C/C++ and CMake Tools extensions and use that.

The Hyprland repo contains a [launch.json](https://github.com/hyprwm/Hyprland/blob/main/example/launch.json) file that you can copy to your `.vscode/` directory in the repo root.

With that, you can build in debug, go to the debugging tab and hit `(gdb) Launch`.

#### Generic

`make debug` to build, `gdb build/Hyprland` to launch and attach a debugger.

### Nix

Check out [the Nix contributing and debugging page](../nix/contributing-and-debugging).

## Development environment

### Setup

Make a copy of your config in `~/.config/hypr` called `hyprlandd.lua`.
`Debug` builds automatically use `hyprlandd.lua` in the default search path, but `--config ~/path/to/conf.lua` can be passed to override the configuration file location.

#### Recommended debug config changes

- Remove _all_ autoexec directives from your config.
- Change default modifier for binds (e.g. `SUPER` → `ALT`)

#### Launch the dev env

Launch the output `Hyprland` binary in `./build/` _when logged into a Hyprland session_.
A new window should open with Hyprland running inside of it.
You can now test stuff in this nested session without worrying about nuking your actual session.

I'd also recommend launching Hyprland with a debugger, like `gdb`.
Your IDE (if you use one) can likely do it for you, otherwise `gdb ./build/Hyprland` should suffice.
Now when Hyprland crashes, GDB will stop and allow you to inspect the current state with commands like `bt`, `frame`, `print`, etc.
An IDE will allow you to do so graphically.

## LSP and Formatting

If you want proper LSP support in an editor that doesn't automatically set it up, use clangd.
You'll probably notice there will be a bunch of warnings because we haven't generated compile commands, to do this run:

```sh
cmake -S . -B build/ -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
```

Also, before submitting a PR please format with clang-format.
To do this only on your changes, run `git-clang-format` in your project's root directory.

## Logs, dumps, etc.

You can use the logs and the GDB debugger, but running Hyprland in debug compile as a driver and using it for a while might give more insight to the more random bugs.

When Hyprland crashes, use `coredumpctl` and then `coredumpctl info PID` to see the dump. See the instructions below for more info about `coredumpctl`.

You can also use the amazing command

```sh
watch -n 0.1 "grep -v \"arranged\" $XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log | tail -n 40"
```

for live logs.
(Replace `hyprland` with `hyprlandd` for debug builds.)

### How do I get a coredump?

See [`ISSUE_GUIDELINES.md`](https://github.com/hyprwm/Hyprland/blob/main/docs/ISSUE_GUIDELINES.md).

---

---
weight: 20
title: Issue guidelines
---

Due to the influx of low quality or incomprehensible issues, we prefer to begin possible bug reports or feature requests as *discussions*.
We will elevate them to issues if they can be confirmed by a member to be relevant, and once enough information about the problem has been gathered.

> [!NOTE] **Why?**
> We are volunteers, doing this in our free time.
> Out of respect, please read this document _fully_ before posting an issue _or_ discussion.
> If you can spend a few minutes reading this, it saves us, the developers, much more time overall, so we can deliver fixes and features faster.
>
> Thank you!

## Issue Guidelines

If you are experiencing a bug, or missing a feature, please do not open an issue.
Instead, we ask you to open a [discussion](https://github.com/hyprwm/Hyprland/discussions).

### Before you start a discussion

_Search the discussions and issues thoroughly_.
It's likely that there's already one open for your bug/feature that you can just upvote, instead of wasting both your time writing a new one and our time closing it and redirecting you.

### The lifecycle of a discussion

A discussion is opened by a user.

For bugs:
- If a discussion is solved, user error, or not a Hyprland issue, it gets closed.
- If a discussion is a Hyprland problem, but cannot be tied to Hyprland in a clear way, or is not reproducible, it stays a discussion until that changes.
- If a discussion is reproducible, a member of Hyprland promotes the discussion to an issue by opening an issue with the key information and links the original discussion.

> [!NOTE]
> To get logs for your bug, please see [Crashes and Bugs](../../crashes-and-bugs).

For feature requests:
- If a discussion describes a feature that is already possible (via scripts, features, or official tools), invalid, or not applicable, it gets closed.
- If a discussion describes a feature that is _not_ already possible, it stays a discussion.
- If a discussion describes a feature that is _not_ already possible, and it gathers enough attention, a member may promote it to an issue by opening an issue with the key information and links the original discussion.

Please note we are all volunteers and our numbers are small, so issues may stay idle.

### Gathering attention for your discussion / a discussion you care about

Avoid posting comments such as "when fix?".
Instead, upvote the discussion or issue (if one exists).

If a discussion has reached 5 upvotes or more, and it hasn't been promoted, you may ping a member in the discussion
(`@vaxerski`, `@fufexan` or `@notashelf` are the most likely ones to work).

Please ***do not*** ping the members just because the discussion has become stale, or failed to gather attention.
If that is the case, attempt to bring it back on track by posting *further* relevant information that might spark a discussion, or tell people interested about the discussion so that they can upvote it.

---

---
weight: 30
title: PR guidelines
---

## PR Requirements

- Clean, not hacky code
- Described changes and _why_ they were there
- Following the style (see below)

## AI Policy

It is **mandatory** to follow our [AI Policy](https://github.com/hyprwm/.github/blob/main/policies/AI_USAGE.md).
Failure to do so may lead to being banned from opening any PRs in the future!

## Code Style

Please read this if you are submitting a PR, in order to minimize the amount of style nits received, and save the time for the maintainers.

### Before you submit

Make sure you ran clang-format: `make format-fix`

Check if your changes don't violate `clang-tidy`.
Usually this is built into your IDE.

### Clang-format

This is non-negotiable.
Your code **must** be formatted.

### Clang-tidy

Clang-tidy violations are not hard requirements, but please try to minimize them, and _only_ ignore them if it's absolutely necessary.

It is tweaked so that in 99% of cases you absolutely should fix it.

### Testing

Please check the [Tests](../tests) page for information about tests in Hyprland, and related projects.

No test regressions is a _must_, while new tests are _required_ if possible to test (e.g., graphical stuff is not testable).

### Other

Some stuff clang-tidy/clang-format won't catch:
- No uninitialized _primitives_ (int, float, double, size_t, etc.)
- No short if braces. if your if/else body contains 1 _line_ (not 1 statement) do not put `{}` around it.
  - The above rule does not apply to loops, etc.
- Consider adding a `;` inside of empty function bodies
- Whenever you're initializing vectors arrays or maps with a lot of elements, add a `,` after the last element to make the styling nicer
- Consider forward-declaring things in headers if possible instead of including. Speeds up compile times.
- no `using namespace std;`, and `using namespace (anything else)` is only allowed in source files, not headers.
- prefer guards rather than nesting. `if(!valid) return;` is much better than `if (valid) { /* a billion things */ }`

### Naming conventions

The code should use `camelCase`, with an `m_` prefix if the variable is a member of a class (not a struct).

Additionally:
- classes have a prefix of `C`: `CMyClass`
- structs have a prefix of `S`: `SMyStruct`
- interfaces have a prefix of `I`: `IMyInterface`
- global pointers for singletons have a prefix of `g_`: `g_someManager`
- constant variables are in CAPS: `const auto MYVARIABLE = ...`

## General code requirements

### No raw pointers

This is a simple rule --- don't use raw pointers (e.g., `CMyClass*`) unless _absolutely necessary_.
You have `UP`, `SP` and `WP` at your disposal.
These are unique, shared and weak pointers respectively.

### No malloc

Unless absolutely necessary, do not use `malloc`/`free`.
You _will_ forget to free the memory.

### Avoid dubious cleanups

If a function is a C-style allocator (e.g., `some_c_call_make_new()`), it will likely require a `some_c_call_free()`.
In these cases, either:
- wrap the thing in a C++ class, or
- if used only within one function, use a `CScopeGuard` to always free it when the function exits.

### Use the STL

Generally, use the STL instead of trying to reinvent the wheel.

### Use hyprutils

Hyprutils provides a lot of utilities that are well-suited for Hyprland (and other hypr\* projects) specifically.
Use them.

### No absolute includes from /src

Imagine this scenario:

```
src/
   a/
      a.hpp
   b/
      b.hpp
```

If you are in `a.hpp` and want to include `b.hpp`, you _must_ use `../b/b.hpp`, and _cannot_ use `b/b.hpp`.
The latter will break plugins.

One exception you might notice in the code is absolute paths from the root are allowed (e.g., `protocols/some-protocol.hpp`)

---

---
weight: 10
title: Wiki writing guidelines
---

## Wiki engine notes

Markdown (and thus Hugo) automatically concatenate pairs of lines, unless a newline or a double space is present at the end of the first line in the pair.

Templates can be invoked by <code>\{\{< shortcode >\}\}</code> or <code>\{\{% shortcode %\}\}</code>.
The correct usage can be found in comments in each shortcode's file.

The Hextra theme's shortcodes can be found [here](https://github.com/imfing/hextra/tree/main/layouts/_shortcodes).
This wiki's shortcodes can be found [here](https://github.com/hyprwm/hyprland-wiki/tree/main/layouts/_shortcodes).

The version selector is generated by a shortcode, which reads list of versions from Hugo's `config.toml`.

## General styling notes

All styling described here must apply everywhere possible (e.g. Markdown does not allow a multi-sentence table field to be split across lines).

Page content should follow the [xkcd 1285](https://xkcd.com/1285) formatting style, i.e. a new line after every sentence.
These line breaks are ignored when content is rendered, but help reduce diff size and make the source more readable for documentation writers.

See [this article](https://writingslowly.com/2025/01/13/semantic-line-breaks-are-a.html) and the [Semantic Line Breaks specification](https://sembr.org) for details that aren't in comic panel form.

In addition:
- Code blocks should use 4 spaces, rather than tabs or some other indentation scheme.
- Warnings must go to the top of the section.
- All abbreviations must be capitalized.
- Spelling must follow standard United States English conventions.
- Trailing punctuation must be placed outside of any quotation marks.

When adding a new dispatcher, position arguments in a way, that answers the following questions:
- What is addressed?
- What action to perform?
- How to perfom the action?

HTML comments (`<!-- -->`) are not visible in the rendered page, but are useful for maintenance.
Use standard tags (`WARNING: `, `NOTE: `, `TODO: `, `SORT: `) in the first line of the comment when appropriate.
Keep comment messages one space after the tag (`TODO: body here`).

## Sorting config options

Tables of config options are sorted in the following manner:

{{% steps %}}

### Global toggle?

An `enabled` option, if it exists, must always be listed first.

### Display or display-like?

If the table includes `output`, `position`, `scale`, `transform`, or `rotation`, these must be placed next, in the order they are listed here.

### Other

Remaining options must be sorted alphabetically, with an exception (below) for cases where this would obscure meaning.

### Special order

In some cases, multiple options act in a related manner, and would be more helpful if sorted together.
If any additional sorting was performed, add a comment (beginning with `SORT: `) before the table to describe it.
Descriptions are free-form, they simply need to be understandable by others.
Also, mention the sorting in your PR.

{{% /steps %}}

## Option descriptions

Descriptions must start with capital letter, and end _without_ a period (full stop).

Keep descriptions concise.
If additional explanation is needed, create a subsection below, and link to it from the table.

If an option only supports a particular set of predefined values, list them in the description.
If there are more than four such predefined values, create a subsection and link to it from the table.

If an option has limits that are enforced by the config manager, specify them in the `Limits` field with respect to the type.

---

---
weight: 40
title: Tests
---

Hyprland and some other projects under the hypr\* umbrella have _tests_ that try to catch bugs and regressions before code is merged.

Building in Debug will by default build tests.

## Running tests

Hyprland provides a `test` Makefile target, so the full suite can be run simply via:

```sh
make test
```

Unit and integration tests can also be run separately; see the remainder of this section for details.

### GTests

GTests are GoogleTests that are _unit tests_.
These tests simply check how some elements behave when they can run on their own.

For Hyprland, run:

```sh
make gtest
```

In other projects, invoke ctest manually:

```sh
ctest -j$(nproc) -C Debug --test-dir=build
```

And make sure your tests pass.

### Hyprland's hyprtester

A lot of Hyprland's code cannot be unit tested, thus we have our own Hyprtester binary which runs Hyprland and issues commands and expects results.

#### Run all tests

To run Hyprtester, execute the following in a debug build:

```sh
./build/hyprtester/hyprtester -c hyprtester/test.lua -b ./build/Hyprland -p hyprtester/plugin/hyprtestplugin.so
```

or invoke the relevant Makefile target:

```sh
make hyprtest
```

*This will run for a while!*
At the end, it will print summary results of how many tests passed, and how many failed.

The goal of failed tests is to be **0**.

#### Run selected tests

When you only want to run specific tests, just list their names (without group/file name) on the command line, for example:

```sh
./build/hyprtester/hyprtester dwindleSplit focusMasterPrevious processSpawning -c hyprtester/test.lua -b ./build/Hyprland -p hyprtester/plugin/hyprtestplugin.so
```

or invoke the Makefile target with the extra `HYPRTESTS` variable set:

```sh
make HYPRTESTS="dwindleSplit focusMasterPrevious processSpawning" hyprtest
```

## Submitting new tests

New tests have to either be a GTest, if the thing tested is possible to be unit tested, or a part of hyprtester.

For both test types, you can check the test directories in the project.
GTests live in `tests/`, while hyprtester tests live in `hyprtester/`.

### What to test

If you're submitting a new feature, it's obviously your feature.
For a fix, try to write a test case that would fail before your fix.

For new tests, you can inspect the coverage report.

First, run _both_ ctest and hyprtester.
Then, run (from the repo root):

```sh
gcovr -r . build --html --html-details -o build/coverage.html --gcov-ignore-parse-errors="negative_hits.warn" && xdg-open ./build/coverage.html
```

This will run for a while, then open a report in your browser.
You can see which files have been tested in what amount, and click on the files to see a line-by-line breakdown.

If there are paths untested, we'd be very happy to receive tests for them.

---

---
weight: 50
title: Translations
---

Some parts of the Hyprland ecosystem are localized.
More and more are getting localization frameworks.
This is a short page showing how to contribute translations to Hyprland apps.

## Find the translation file

Here you'll find a list of translation files for hyprapps ready to translate:

- [hyprland](https://github.com/hyprwm/Hyprland/blob/main/src/i18n/Engine.cpp)
- [hyprlauncher](https://github.com/hyprwm/hyprlauncher/blob/main/src/i18n/Engine.cpp)
- [hyprpwcenter](https://github.com/hyprwm/hyprpwcenter/blob/main/src/i18n/Engine.cpp)

_more are coming, this list will be updated_

## Translate

Translations are in C++, but they are straightforward, and don't require much expertise.
You submit a translation via a traditional MR on Github.

### Basic translations (unconditional)

You register a translation for a key and your language code.
For example, for key `TXT_KEY_HELLO`, and language `pl_PL` (Polish), you can:

```cpp
registerEntry("pl_PL", TXT_KEY_HELLO, "Siemka!");
```

Some translations have variables, included like so:

```cpp
registerEntry("pl_PL", TXT_KEY_HELLO, "Siemka, {name}!");
```

### Conditional translations

In some languages, you might want to change your translation based on e.g. the amount (apple vs apples).
In this case, it's a bit more complicated, but it looks like this:

```cpp
registerEntry("pl_PL", TXT_KEY_HELLO, [](const Hyprutils::I18n::translationVarMap& vars) {
    int peopleAmount = std::stoi(vars.at("count"));
    if (peopleAmount == 1)
        return "Mam {count} dziewczynkę anime.";
    int last = peopleAmount % 10;
    int lastTwo = peopleAmount % 100;
    if (last >= 2 && last <= 4 && !(lastTwo >= 12 && lastTwo <= 14))
        return "Mam {count} dziewczynki anime.";
    return "Mam {count} dziewczynek anime.";
});
```

As you can see, you can change the returned string based on some variable.
Please note all variables are strings, so you need to call a standard function like `std::stoi` to obtain an integer.

### Fallbacks

In general, if you are translating into a language with regional variants, if the translations are the same, you don't need two entries.

Order of fallbacks is as follows:
- `xy_ZT`
- `xy_XY`
- `xy_ANYTHING`
- global fallback (usually `en_US`)

So, if you write something for `de_DE`, and the user has `de_AT` but `de_AT` is missing, `de_DE` will be used.

---

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: 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