Hyprgrass: touch screen gestures for Hyprland, with an alpha warning attached

Swipes become workspace moves and shell commands

Hyprgrass exists to fill a gap in Hyprland: the compositor has no native gesture layer for touch input, and a laptop with a touchscreen is otherwise a touch device pretending to be a mouse. The plugin reads touch events and turns them into things Hyprland already understands. The feature list in the repository shows four items marked as done: workspace swipe, custom commands, swipe from edge, and multi-finger swipe.

That list is the whole value proposition, and it is narrow in a useful way. A workspace swipe moves you between workspaces, which is the gesture most people want on a touchscreen. Custom commands mean the gesture can run a script or launcher instead. Swipe from edge gives you a hotspot you can reach without lifting your hand off the screen. Multi-finger swipe distinguishes a two-finger gesture from a one-finger one, so the same screen can carry different actions.

The code is C++ and the project is packaged as a Hyprland plugin, sharing the ecosystem of hyprpm, hyprctl and the plugin wiki. The topic tags on the repository are hyprland and hyprland-plugin, and there is no separate application to install alongside it.

The alpha warning in the README is a real operational warning

The README opens with a warning block, and the details in it are the first thing anyone running this should read. There used to be bugs that render your touch device unusable until you unload the plugin or close Hyprland, with issue 27 linked as the reference. The recommendation is to keep a keyboard in hand the first time you try it, and the project states plainly that it is still in alpha with breaking changes expected.

This is worth taking literally rather than as boilerplate. A gesture plugin sits in the input path, so a fault in it does not degrade the feature, it removes the ability to control the machine by touch. The recorded bug did not merely misfire a swipe, it made the device unusable until the plugin was unloaded. On a desktop with a keyboard that is annoying. On a tablet-style Hyprland setup with no physical keyboard, the same fault removes your only input method.

The alpha label also means the configuration format can change. The README points to a configuration document in the docs folder for settings, and any custom commands or edge zones you define should be expected to need adjusting after an update.

hyprpm handles the install, but the build dependencies are yours to install

Installing through hyprpm takes two commands, and the documentation is explicit that the dependencies come first. They are glm for the math headers, plus meson and ninja as build dependencies.

glm

# build dependencies
meson
ninja

Once those are present, the plugin is added and enabled through hyprpm:

hyprpm add https://github.com/horriblename/hyprgrass
hyprpm enable hyprgrass

That is the shortest path to a running plugin, and the documentation also points at the Hyprland wiki page on using plugins with hyprpm for the wider picture. One detail is easy to miss and worth copying: you can add `exec-once = hyprpm reload -n` to your Hyprland config so plugins load at startup, and the `-n` flag makes hyprpm send a notification if something goes wrong, such as an update being needed. Without that flag a failed plugin load can be silent, which on a machine where the plugin is your touch input is a bad trade.

A debug build turns an unreadable crash into a stack trace

The most useful thing in the documentation for anyone hitting the bugs the warning describes is the debug build path. The project explains the reason plainly: debug builds give a more detailed stack trace during crashes, which helps identify the problem when reporting it.

git clone https://github.com/horriblename/hyprgrass
cd hyprgrass

meson setup build -Dbuildtype=debug
meson compile -Cbuild

# note that relative paths won't work
hyprctl plugin load "$PWD/build/src/libhyprgrass.so"

The resulting shared object is loaded with hyprctl plugin load, and the comment about relative paths is a genuine gotcha: the load path has to be absolute, so the command uses the $PWD prefix. Manual compilation is the same build without the debug flag, using meson setup build and ninja -C build, and the only option the documentation lists for the setup step is -Dbuildtype=debug.

Crash logs land in a predictable place. The README asks you to attach the log from ~/.cache/hypr/hyprlandCrashReport{pid}.txt when you report a crash, which means the maintainer has a defined way to receive the information they need rather than asking for screenshots.

The Nix route exists mainly so Hyprland versions line up

For Nix and home-manager users the plugin ships as a flake, and the README recommends flakes in unusually candid terms. The flake input has one requirement that the file marks as important: the hyprgrass input must follow the hyprland input, so both resolve to the same Hyprland source.

{
   inputs = {
      # ...
      hyprland.url = "github:hyprwm/Hyprland";
      hyprgrass = {
         url = "github:horriblename/hyprgrass";
         inputs.hyprland.follows = "hyprland"; # IMPORTANT
      };
   };
}

The reason for the follows attribute is structural rather than cosmetic. A Hyprland plugin is compiled against a particular Hyprland version, so two inputs resolving to different Hyprland revisions would produce a plugin that does not match the compositor it loads into. The home-manager module then lists the plugin package, and optionally a second package for pulse-audio integration, with a pointer to an example README in the repository's examples folder for that integration.

For a system not running Nix, none of this applies, and the hyprpm path remains the only documented route besides manual compilation.

The dependency on Wayfire's touch library explains the C++ build

The acknowledgements section credits the wf-touch library from Wayfire, and some parts of the project are based on AOSP code under Apache License 2.0, kept in a separate LICENSE.aosp file at the repository root. The example plugins are based on Waybar, which is MIT licensed.

This tells you more about the project than the feature list does. Reusing an existing touch input library rather than writing a raw input parser is a sensible trade for a plugin maintained by one person, because touch handling is exactly the area where a mistake locks up the device, which is the failure the README warns about. The cost is a build that needs glm, meson and ninja rather than a script, and a code base with two other licences in play alongside its own BSD-3-Clause.

The BSD-3-Clause licence on the project itself is permissive and carries no copyleft obligation, so a fork can be closed source if that is what you need. The Apache 2.0 and MIT portions retain their own terms, and the repository ships separate licence files for them, so the licence picture is clean as long as you keep those files with your fork.

Release tags stopped in 2024 while the branch kept moving

The maintenance picture is mixed, and the two halves of it point in opposite directions. The repository is not archived and the last push was on 2026-10-19, which is recent work on the default branch. The most recent tagged releases are v0.8.2 on 2024-10-09, v0.8.1 on 2024-08-25, and v0.8.0 on 2024-08-25.

So the tags stopped around two years ago while the branch continued to receive commits. A hyprpm install pulls from the repository rather than a fixed tag, which means you get the recent code, not v0.8.2. That is a double edged position. You get the fixes that came after the last release, and you get a build that the author still calls alpha, with breaking changes expected and no release note to tell you what broke.

There is a VERSION file at the repository root, and the recent releases are tagged versions rather than a separate changelog. For an alpha plugin that is tolerable. For anything you depend on, the relevant question is not whether the code is fresh but whether the last push was reviewed and tested by the people running it.

Editorial conclusion

Adopt Hyprgrass if you run Hyprland on a touch device and want swipe to move between workspaces, and you are prepared to handle a plugin that the author still labels alpha with breaking changes expected. Do not adopt it on a machine where a frozen input device would leave you unable to type, since the project documents a past bug that made touch devices unusable until the plugin was unloaded. Before you enable it, build the debug version with meson setup build -Dbuildtype=debug and load libhyprgrass.so with hyprctl plugin load, so a crash gives you a stack trace and the report path is ~/.cache/hypr/hyprlandCrashReport{pid}.txt.

Frequently asked questions

Official sources

1. horriblename/hyprgrass on GitHub
2. Issues
3. License: BSD-3-Clause
4. README
5. Releases