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

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

# Hyprland Plugins Reference

---
weight: 10
title: Using plugins
---

This page will tell you how to use plugins.

## Disclaimers

> [!WARNING]
> Plugins are written in C++ and will run as a part of Hyprland.
> Make sure to _always_ read the source code of the plugins you are going to use and to trust the source.
> Writing a plugin to wipe your computer is easy.
>
> _**Never**_ trust random `.so` files you receive from other people.

## Getting plugins

Plugins come as _shared objects_, aka. `.so` files.

Hyprland does not have any "default" plugins, so any plugin you may want to use you will have to find yourself.

## Installing / Using plugins

It is _highly_ recommended you use the Hyprland Plugin Manager, `hyprpm`.
For manual instructions, see [here](#manual).

### hyprpm

> [!NOTE]
> If you are using [permission management](../../configuring/core/advanced-configuration/permissions), you should allow hyprpm to load plugins by adding this to your config:
>
> ```lua
> hl.permission("/usr/(bin|local/bin)/hyprpm", "plugin", "allow")
> ```
>
> Otherwise you'll get a popup asking for permission every time hyprpm tries to load a plugin.

Make sure you have `hyprpm` installed (if packaged separately from Hyprland itself), as well as the required dependencies:
`cpio`, `cmake`, `git`, `meson` and `gcc`.
You might also need `-dev` packages of Hyprland's dependencies if your distro splits binaries and headers (e.g. Fedora or Debian).

Find a repository you want to install plugins from. As an example, we will use [hyprland-plugins](https://github.com/hyprwm/hyprland-plugins).

```sh
hyprpm add https://github.com/hyprwm/hyprland-plugins
```

Once it finishes, you can list your installed plugins with:

```sh
hyprpm list
```

Then, enable or disable them via `hyprpm enable name` and `hyprpm disable name`.

In order for the plugins to be loaded into Hyprland, run `hyprpm reload`.

You can add `hyprpm reload` to your Hyprland config's autostarts to have plugins loaded at startup.
Optionally add the `-n` flag to get a notification that the plugin loaded successfully (eye candy).
Note regardless of whether `-n` is present or not, the `reload` command will generate a notification for warning and error events.

To update your plugins, run `hyprpm update`.

For all options of `hyprpm`, run `hyprpm -h`.

### Manual

Different plugins may have different build methods, refer to their instructions.

If you don't have Hyprland headers installed, clone Hyprland, checkout to your version, build Hyprland, and run `sudo make installheaders`.
Then build your plugin(s).

To load plugins manually, use `hyprctl plugin load path`.

You can unload plugins with `hyprctl plugin unload path`.

You can also load plugins with Lua `hl.plugin.load(path)`.

> [!WARNING]
> All paths have to be absolute!

## FAQ About Plugins

### How do I use them in my config?

Example:

```lua
hl.on("hyprland.start", function()
    hl.exec_cmd("hyprpm reload")
end)

function M.setup_vkfix()
    if hl.plugin.csgo_vulkan_fix ~= nil then
        hl.plugin.csgo_vulkan_fix.vkfix_app({ app = "cs2", w = 2304, h = 1440 })
        hl.config({
            plugin = {
                csgo_vulkan_fix = {
                    fix_mouse = false
                }
            }
        })
    end
end
```

The `if` is there so that we don't get an error if the plugin is not loaded yet. Not all plugins can be detected this way. This example tries to load manually built plugin with Lua and configures it if that succeeded:

```lua
function is_plugin_loaded(name)
    for _,v in pairs(hl.get_loaded_plugins()) do
        if v.name == name then return true end
    end
    return false
end

hl.plugin.load("/absolute/path/to/example.so")

if is_plugin_loaded("example") then
    hl.config({
        plugin = {
            example = {
                ...
            }
        }
    })
end
```

### My Hyprland crashes!

Oh no.
Oopsie.
Usually means a plugin is broken.
`hyprpm disable` it.

### How do I list my loaded plugins?

`hyprctl plugin list`

### How do I make my own plugin?

See [here](../development/getting-started).

### Where do I find plugins?

You can find our featured plugins at [hypr.land/plugins](https://hypr.land/plugins/).
You can also see a list at [awesome-hyprland](https://github.com/hyprland-community/awesome-hyprland#plugins).
Note that it may not be complete.
Lastly, you can try searching around GitHub for the `"hyprland plugin"` keyword.

### Are plugins safe?

As long as you read the source code of your plugin(s) and can see there's nothing bad going on, they will be safe.

### Do plugins decrease Hyprland's stability?

Hyprland employs a few tactics to unload plugins that crash.
However, those tactics may not always work.
In general, as long as the plugin is well-designed, it should not affect the stability of Hyprland.

---

---
weight: 20
title: Development
---

This section describes the process of developing plugins for Hyprland.
It is intended to be read by developers, not end users.

- [Getting started](./getting-started)
- [Plugin guidelines](./plugin-guidelines)
- [Advanced](./advanced)

---

---
weight: 10
title: Getting started
---

This page documents the basics of making your own Hyprland plugin from scratch.

## How do plugins work?

Plugins are basically dynamic objects loaded by Hyprland.
They have (almost) full access to every part of Hyprland's internal process, and as such, can modify and change way more than a script.

## Prerequisites

In order to write a Hyprland plugin, you will need:

- Knowledge of C++
- The ability to read
- A rough understanding of the Hyprland internals (you _can_ learn this alongside your development work)

## Making your first plugin

Open your favorite code editor.

Make a new directory, in this example we will use `MyPlugin`.

_**→ If you have the Hyprland headers**_

If you install with `make install`, you should have the headers.
In that case, no further action is required.

_**→ If you don't have the Hyprland source cloned**_

Clone the Hyprland source code to a subdirectory, in our example `MyPlugin/Hyprland`.
Run `cd Hyprland && make debug && sudo make installheaders && cd ..`.

Now that you have the Hyprland sources set up, you can either start from scratch if you know how, or take a look at some simple plugins in the [official plugins repo](https://github.com/hyprwm/hyprland-plugins) like for example `csgo-vulkan-fix` or `hyprwinwrap`.

### The basic parts of the plugin

Starting from the top, you will have to include the plugin API:

```cpp
#include <hyprland/src/plugins/PluginAPI.hpp>
```

Feel free to take a look at the header.
It contains a bunch of useful comments.

We also create a global pointer for our handle:

```cpp
inline HANDLE PHANDLE = nullptr;
```

We will initialize it in our plugin init function later.
It serves as an internal "ID" of our plugin.

Then, there is the API version method:

```cpp
// Do NOT change this function.
APICALL EXPORT std::string PLUGIN_API_VERSION() {
    return HYPRLAND_API_VERSION;
}
```

This method will tell Hyprland what API version was used to compile this plugin.
Do NOT change it.
It will be set to the correct value when compiling.

Skipping over some example handlers, we have two important functions:

```cpp
APICALL EXPORT PLUGIN_DESCRIPTION_INFO PLUGIN_INIT(HANDLE handle) {
    PHANDLE = handle;

    const std::string COMPOSITOR_HASH = __hyprland_api_get_hash();
    const std::string CLIENT_HASH = __hyprland_api_get_client_hash();

    // ALWAYS add this to your plugins. It will prevent random crashes coming from
    // mismatched header versions.
    if (COMPOSITOR_HASH != CLIENT_HASH) {
        HyprlandAPI::addNotification(PHANDLE, "[MyPlugin] Mismatched headers! Can't proceed.",
                                     CHyprColor{1.0, 0.2, 0.2, 1.0}, 5000);
        throw std::runtime_error("[MyPlugin] Version mismatch");
    }

    // ...

    return {"MyPlugin", "An amazing plugin that is going to change the world!", "Me", "1.0"};
}

APICALL EXPORT void PLUGIN_EXIT() {
    // ...
}
```

The first method will be called when your plugin gets initialized (loaded), and is thus _required_.
You can, and probably should, initialize everything you may want to use in there.
Make sure to store your `HANDLE` as it's going to be required for API calls.

It's worth noting that adding config variables are _only_ allowed in this function.

The return value should be the `PLUGIN_DESCRIPTION_INFO` struct which lets Hyprland know about your plugin's name, description, author and version.

The second method is not required, and will be called when your plugin is being unloaded by the user.

If your plugin is being unloaded because it committed a fault, this function will _not_ be called.

You do not have to unload layouts, remove config options, remove dispatchers, window decorations or unregister hooks in the exit method.
Hyprland will do that for you.

### Setting up a development environment

In order to make your life easier, it's a good idea to work on a nested debug Hyprland session.
Unless you need to test some things that require real hardware (e.g. trackpad gestures), you definitely should use a nest.

See [the Contributing Section](../../../contributing-and-debugging/#development-environment) for instructions on setting up a development environment.

### Loading / reloading plugins

Build your plugin, and you can load it in your nest with

```sh
hyprctl plugin load /absolute/path/to/plugin.so
```

and unload with

```sh
hyprctl plugin unload /absolute/path/to/plugin.so
```

The normal development cycle would usually mean loading the plugin, checking your changes, building the plugin with new changes, unload + load, and repeat.

You can have a one-liner like so:

```sh
hyprctl plugin unload /absolute/path/to/plugin.so ; hyprctl plugin load /absolute/path/to/plugin.so
```

as a "reload" of the plugin.

### More advanced stuff

Take a look at the `src/plugins/PluginAPI.hpp` header.
It has comments to every method to let you know what it is.

For more explanation on a few concepts, see [Advanced](../advanced) and [Plugin Guidelines](../plugin-guidelines).

---

---
weight: 30
title: Advanced
---

This page documents a few advanced things about the Hyprland Plugin API.

## Accessing private members

If you need access to a private member of a Hyprland class, you can surround includes with a macro which will change the visibility to public.
Note that some Hyprland files include the STL which may end up breaking if you attempt this.
If you encounter this issue, make sure to include the offending STL import before the section where you include the Hyprland file.

```cpp
#define private public
#include <hyprland/src/plugins/PluginAPI.hpp>
#include <hyprland/src/render/OpenGL.hpp>
#include <hyprland/src/desktop/Window.hpp>
#include <hyprland/src/layout/IHyprLayout.hpp>
#undef private
```

## Using Function Hooks

> [!WARNING]
> Function hooks are only available on `AMD64` (`x86_64`).
> Attempting to hook on any other arch will make Hyprland simply ignore your hooking attempt.

Function hooks are intimidating at first, but when used properly can be _extremely_ powerful.

Function hooks allow you to intercept any call to the function you hook.

Let's look at a simple example:

```cpp
void Events::listener_monitorFrame(void* owner, void* data)
```

This will be the function we want to hook.
`Events::` is a namespace, not a class, so this is just a plain function.

```cpp
// make a global instance of a hook class for this hook
inline CFunctionHook* g_pMonitorFrameHook = nullptr;
// create a pointer typedef for the function we are hooking.
typedef void (*origMonitorFrame)(void*, void*);

// our hook
void hkMonitorFrame(void* owner, void* data) {
    (*(origMonitorFrame)g_pMonitorFrameHook->m_pOriginal)(owner, data);
}

APICALL EXPORT PLUGIN_DESCRIPTION_INFO PLUGIN_INIT(HANDLE handle) {
    // stuff...

    // create the hook
    static const auto METHODS = HyprlandAPI::findFunctionsByName(PHANDLE, "listener_monitorFrame");
    g_pMonitorFrameHook = HyprlandAPI::createFunctionHook(handle, METHODS[0].address, (void*)&hkMonitorFrame);

    // init the hook
    g_pMonitorFrameHook->hook();

    // further stuff...
}
```

We have just made a hook.
Now, whenever Hyprland calls `Events::listener_monitorFrame`, our hook will be called instead!

This way, you can run code before/after the function, modify the inputs or results, or even block the function from executing.

`CFunctionHook` can also be unhooked whenever you please. Just run `unhook()`.
It can be rehooked later by calling `hook()` again.

### Member functions

For members (e.g., `CCompositor::focusWindow(CWindow*, wlr_surface*)`) you will also need to add the thisptr argument to your hook:

```cpp
typedef void (*origFocusWindow)(void*, CWindow*, wlr_surface*);

void hkFocusWindow(void* thisptr, CWindow* pWindow, wlr_surface* pSurface) {
    // stuff...

    // and if you want to call the original...
    (*(origFocusWindow)g_pFocusWindowHook->m_pOriginal)(thisptr, pWindow, pSurface);
}

APICALL EXPORT PLUGIN_DESCRIPTION_INFO PLUGIN_INIT(HANDLE handle) {
    // stuff...

    static const auto METHODS = HyprlandAPI::findFunctionsByName(PHANDLE, "focusWindow");
    g_pFocusWindowHook = HyprlandAPI::createFunctionHook(handle, METHODS[0].address, (void*)&hkFocusWindow);
    g_pFocusWindowHook->hook();

    // further stuff...
}
```

> [!WARNING]
> Please note method lookups are slow and should not be used often.
> The entries _will not_ change during runtime, so it's a good idea to make the lookups `static`.

### Why use findFunctionsByName?

Why use that instead of, e.g., `&CCompositor::focusWindow`?
Two reasons:

1. Less breakage.
   Whenever someone updates Hyprland, that address might become invalid.
   findFunctionsByName is more resilient.
   As long as the function exists, it will be found.
1. Error handling.
   The method array contains, besides the address, the signatures.
   You can verify those to make 100% sure you got the right function, or throw an error if it was not found.

## Using the config

You can register config values in the `PLUGIN_INIT` function:

```cpp
APICALL EXPORT PLUGIN_DESCRIPTION_INFO PLUGIN_INIT(HANDLE handle) {
    // stuff...

    HyprlandAPI::addConfigValue(PHANDLE, "plugin:example:exampleInt", SConfigValue{.intValue = 1});

    // further stuff...
}
```

Plugin variables _**must**_ be in the `plugins:` category.
Further categories are up to you.
It's generally a good idea to group all variables from your plugin in a subcategory with the plugin name (e.g., `plugins:myPlugin:variable1`).

For retrieving the values, call `HyprlandAPI::getConfigValue`.

Please remember that the pointer to your config value will never change after `PLUGIN_INIT`, so to greatly optimize performance, make it static:

```cpp
static auto* const MYVAR = &HyprlandAPI::getConfigValue(PHANDLE, "plugin:myPlugin:variable1")->intValue;
```

## Further

Read the API at `src/plugins/PluginAPI.hpp`, check out the [official plugins](https://github.com/hyprwm/hyprland-plugins).

And, most importantly, have fun!

---

---
weight: 20
title: Plugin guidelines
---

This page documents the recommended guidelines for making a stable and neat plugin.

## Making your plugin compatible with hyprpm

In order for your plugin to be installable by `hyprpm`, you need a manifest.

`hyprpm` will parse `hyprload` manifests just fine, but it's recommended to use the more powerful hyprpm manifest.

Make a file in the root of your repository called `hyprpm.toml`.

### Repository metadata

At the beginning, put some metadata about your plugin:

```toml {filename="hyprpm.toml"}
[repository]
name = "MyPlugin"
authors = ["Me"]
commit_pins = [
    ["3bb9c7c5cf4f2ee30bf821501499f2308d616f94", "efee74a7404495dbda70205824d6e9fc923ccdae"],
    ["d74607e414dcd16911089a6d4b6aeb661c880923", "efee74a7404495dbda70205824d6e9fc923ccdae"]
]
```

`name` and `authors` are required.
`commit_pins` are optional.
See [commit pins](#commit-pins) for more info.

### Plugins

For each plugin, make a category like this:

```toml {filename="hyprpm.toml"}
[plugin-name]
description = "An epic plugin that will change the world!"
authors = ["Me"]
output = "plugin.so"
build = [
    "make all"
]
```

`description`, `authors` are optional.
`output` and `build` are required.

`build` are the commands that `hyprpm` will run in the root of the repo to build the plugin.
Every command will reset the current working directory to the repo root.

`output` is the path to the output `.so` file from the root of the repo.

### Commit pins

Commit pins allow you to manage versioning of your plugin.
They are pairs of `hash,hash`, where the first hash is the Hyprland commit hash, and the second is
your plugin's corresponding commit hash.

For example, in the manifest above, `d74607e414dcd16911089a6d4b6aeb661c880923` corresponds to Hyprland's `0.33.1` release.
This means that if someone is running `0.33.1`, `hyprpm` will reset your plugin to commit hash `efee74a7404495dbda70205824d6e9fc923ccdae`.

It's recommended you add a pin for each Hyprland release.
If no pin matches, latest git will be used.

## Formatting

Although Hyprland plugins are not _required_ to follow Hyprland's formatting, naming conventions, etc., it might be a good idea to keep your code consistent.
See [`.clang-format`](https://github.com/hyprwm/Hyprland/blob/main/.clang-format) in the Hyprland repo.

## Usage of the API

It's always advised to use the API entries whenever possible, as they are guaranteed stability as long as the version matches.

It is, of course, possible to use the internal methods by just including the proper headers, but it should not be treated as the default way of doing things.

Hyprland's internal methods may be changed, removed or added without any prior notice; though methods that "seem" fundamental (e.g., `focusWindow` `mouseMoveUnified`) are unlikely to change their general way of functioning.

## Function Hooks

Function hooks allow your plugin to intercept all calls to a function of your choice.
They are to be treated as a last resort, as they are the easiest thing to break between updates.

Always prefer using Event Hooks.

## Threads

The Wayland event loop is strictly single-threaded.
It is not recommended to create threads in your code, unless they are fully detached from the Hyprland process (e.g., saving a file).

---

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