# Hexecute: a Wayland launcher you trigger by drawing a gesture

> Hexecute is a gesture based launcher for Wayland. You bind it to a key in your compositor, and when you want to open something you draw a shape on the screen with the mouse, the shape is matched against the gestures you have taught it, and the matching command runs. The gestures live in a JSON file you can share.

**m31-galaxy/Hexecute** — Launch apps by casting spells! 🪄

- Repository: https://github.com/m31-galaxy/Hexecute
- Website: https://hexecute.app
- Stars: 700 · Forks: 29
- Language: C
- License: GPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/m31-galaxy-hexecute

## A launcher triggered by a shape on the screen

Hexecute is a gesture based launcher for Wayland, and the project's own framing is that you launch apps by casting spells. The demo in the repository is an animated recording of that idea rather than a screenshot.

The mechanism is a key binding plus a drawn shape. You bind the program to a key in your compositor, the program takes over the pointer, you draw something on the screen, and the shape is matched against the gestures the program has learned. The command that was associated with that shape runs.

The key binding is the documented integration point, and the project is explicit that this is the recommended way to use it. The examples it gives all use the same combination, the Windows key and the space bar, in two compositors. For Hyprland the line goes into the compositor configuration.

```ini
bind = SUPER, SPACE, exec, hexecute
```

For Sway the equivalent goes into the sway configuration file.

```ini
bindsym $mod+space exec hexecute
```

That is the whole contract between Hexecute and the desktop, and it is deliberately small. There is no desktop entry, no panel, no icon, and no daemon running all the time. The program is started when you want it and stops when it is done, and the only state it keeps is the file of learned gestures.

The project is GPL-3.0 licensed, the site is hexecute.app, and the release history is short, with v0.1.0 in October 2025 and v0.2.0 the same day, and the last push to the repository on 2026-06-25.

## Teaching it a gesture takes three drawings

The learning step is a command with the application to launch as its argument, and it works by watching you draw the same shape three times.

```bash
hexecute --learn [command]
```

The program starts, waits for you to draw, and maps the shape you drew to the command. The documentation says to draw the chosen gesture three times for it to be mapped, and the animation in the repository shows that sequence.

Three drawings is a small design decision with a clear purpose. A single drawing could be a slip of the hand, and two could still be a coincidence of where you moved the mouse. Requiring the same shape three times means the gesture is a pattern the user actually repeats, and it means the recorded shape has a chance to be the average of three attempts rather than one lucky stroke.

The argument is the command to run, which means the mapping is not limited to launching applications. A gesture could be bound to anything the shell can run, and the project describes the feature as launching a chosen application, so the learning flow is a general one.

What happens on a match is not documented in detail beyond the demo, but the design implies a live gesture set: the program holds the shapes you have taught it and compares the shape you draw against them, and the closest match wins. The three-draw requirement also means the recorded shape is a template with some tolerance built in, since an exact pixel match would make the feature unusable in practice.

## Listing and removing the gestures you have

Two commands cover the management side, and they are deliberately small.

To see what the program has learned, you run the list command.

```bash
hexecute --list
```

To get rid of one, you name the gesture to the remove command.

```bash
hexecute --remove [gesture]
```

Both work on the stored set rather than on a running session, which means you can inspect and prune your gestures without being in the middle of a launch, and you can do it from a terminal the same way you learn them.

The remove command takes a gesture as its argument rather than an index or an identifier, which suggests the gestures are named or described in a way the user recognises, and that a gesture is something you look at and think of as a shape rather than as a row in a table. That is a small thing, but it is the difference between a tool whose state is understandable and one where the state is a list of opaque records.

The commands are also the same commands the compositor binding launches, so there is no separate utility to install and no daemon to keep alive. The program is a single binary that behaves differently depending on its flags, and the flags are documented in one short section of the project readme.

## The gesture file is the whole of the state

Every gesture you have taught Hexecute is saved in one file, in the configuration directory of the user, in a file called gestures.json.

The documentation says that this file can be manually shared, edited, backed up, or swapped. That single sentence is what makes the tool more than a toy, because it means the gesture set is data you own rather than something trapped in a program's internal state.

Sharing is the obvious use. If a colleague uses the same compositor and the same key binding, a gestures file can be handed over, and the same shapes will launch the same commands. That is a small file, it is readable, and it can be pasted into a configuration repository alongside the rest of the desktop setup.

Editing it by hand is the second use, and it is enabled by the same property. If the recorded shape for a command is not quite the shape you would draw, the file can be changed rather than re-learned. Backing it up is the third, and for a tool whose entire value is the set of gestures, that is the one that matters most, because losing the file means teaching every gesture again.

Swapping is the fourth, and it is the most interesting, because the file is a self-contained set rather than a fragment of a larger database. A different mapping can be put in place without migrating anything else.

The file lives in the user's configuration directory, which means it follows the same convention as the compositor configuration it is paired with, and it is where a user should look first if a gesture stops working, since the file is the record of what the program thinks it has learned.

## Installing: a Nix flake, a renamed binary, or a build

There are three installation routes, and they are laid out in the order of how much of the system they assume you already have.

The first is Nix. The project leads with it, and the first command runs the program straight from the repository without installing anything.

```bash
nix run github:m31-galaxy/Hexecute
```

To keep it, the profile install adds it to the user's environment.

```bash
nix profile install github:m31-galaxy/Hexecute
```

And for a NixOS configuration, the flake input is declared in the flake file.

```nix
# flake.nix
{
  inputs.hexecute.url = "github:m31-galaxy/Hexecute";
}
```

Then the package is added to the system packages, referring to the default package for the current system.

```nix
# configuration.nix
{
  environment.systemPackages = with pkgs; [
    inputs.hexecute.packages.${pkgs.system}.default
  ];
}
```

The second route is the release page. You download the latest artefact, put it somewhere on the path, and then do two things that are easy to forget. The binary has to be renamed, because the release files carry a version and a build suffix in the name, and it has to be made executable.

```bash
mv hexecute-1.2.3-blah hexecute
chmod +x hexecute
```

The third route is a build from source. You clone the repository, and if Nix is installed you run the flake build. Otherwise you need Go and the dependent Wayland libraries, and the documentation is candid about the awkward part of that, describing them as the Wayland and X11 libraries, with a question mark after the latter.

```bash
mkdir -p bin
go build -o bin ./...
./bin/hexecute
```

Building everything into a bin directory and running the binary from there is the shape of a project with a small number of commands, and the output name matches the name in the key bindings.

## A Go program with one graphics dependency

The repository is a Go module, and the module file is three lines of substance. The module path is the repository path, the Go version is 1.25.1, and there is exactly one requirement, the OpenGL bindings.

That single dependency is the whole third party story of the project, and it is a clue about how the gestures are matched. A gesture recogniser that compares a drawn path against stored paths needs geometry, and the OpenGL bindings are what give a Go program access to that without a graphics engine underneath it. There is no windowing library, no scene graph, and no UI toolkit in the dependency list, which is consistent with a program that draws on the screen through the Wayland compositor and then exits.

The directory layout follows the usual Go convention, with the command line entry points in a cmd directory, the implementation in internal, and the public packages in pkg. The public packages are what another Go program would import, and given that the module is the whole application rather than a library, that directory is probably where the gesture matching and the drawing code live.

The project also ships a flake and a lock file, which is how the Nix build stays reproducible, and the build instructions for Nix are a single command, because the flake carries the toolchain and the library dependencies with it.

One detail in the project metadata is worth flagging for anyone deciding what this is. The repository is recorded as a C project, while the module file, the build instructions, and the source layout are all Go. The recorded language can lag, and here it plainly does, since the code the project tells you to build with is Go and the only compiled dependency is a Go binding.

## Conclusion

Hexecute fits a Wayland user who wants to start an application without reaching for a name, and who is comfortable binding a key in their compositor and drawing on the screen to trigger it. It does not fit a touch-first device, where a drawn gesture is a poor fit for a tap, and it does not fit someone who wants fuzzy text search with a keyboard, because the project is about shapes rather than names. Verify first that your compositor can bind a key to run the binary, since that is the documented integration point, that the downloaded artefact is renamed to the expected name and made executable, since the release names carry a version suffix, and that the gesture file is somewhere you will back up, because it is the only place your learned gestures exist.

## FAQ

### How do I launch an app with Hexecute?

You bind the binary to a key in your compositor and then draw a gesture on the screen. The examples bind the Windows key and the space bar, with a line in the Hyprland configuration and a bindsym line in the Sway configuration, and the drawn shape selects the command that was associated with it.

### How do I teach Hexecute a new gesture?

Run the learn command with the command to launch as its argument, and draw the chosen gesture three times. The program maps the shape you drew to that command, and the three repetitions are what separate a deliberate shape from an accidental movement of the mouse.

### Where are the Hexecute gestures stored?

In a file called gestures.json inside a hexecute directory under the user's configuration directory. The project says the file can be shared, edited, backed up, or swapped by hand, so the gesture set is a file you own rather than state trapped inside the program.

### How do I install Hexecute without Nix?

Download the latest artefact from the release page, put it on the path, rename it to hexecute because the release file carries a version suffix, and make it executable. To build instead, clone the repository and run the Go build into a bin directory, which needs Go and the dependent Wayland libraries installed.

### What is Hexecute written in?

Go. The module file names the module path, requires Go 1.25.1, and lists a single dependency, the OpenGL bindings, which the gesture matching presumably uses. The repository is recorded as a C project in the project metadata, but the build instructions, the module file, and the directory layout are all Go.

## Sources

- [License: GPL-3.0](https://github.com/m31-galaxy/Hexecute/blob/main/LICENSE)
- [m31-galaxy/Hexecute on GitHub](https://github.com/m31-galaxy/Hexecute)
- [Project website](https://hexecute.app)
- [README](https://github.com/m31-galaxy/Hexecute/blob/main/README.md)
- [Releases](https://github.com/m31-galaxy/Hexecute/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/m31-galaxy-hexecute