An unofficial Go wrapper for Hyprland's IPC.
go get -u github.com/thiagokokada/hyprland-go
Look at the examples
directory for examples on how to use the
library.
-
Go: it is a good language to prototype scripts thanks to
go run
, have low startup times after compilation and allow creation of static binaries that can be run anywhere (e.g.: you can commit the binary to your dotfiles, so you don't need to have a working Go compiler!) -
Good developer experience: the API tries to support the most common use cases easily while also supporting low-level usage if necessary. Also includes proper error handling to make it easier to investigate issues
-
Performance: uses tricks like
bufio
andbytes.Buffer
to archieve high performance:# see examples/hyprtabs $ hyperfine -N ./hyprtabs # 1 window in workspace Benchmark 1: ./hyprtabs Time (mean ± σ): 5.5 ms ± 2.0 ms [User: 0.8 ms, System: 3.0 ms] Range (min … max): 2.2 ms … 11.8 ms 443 runs $ hyperfine -N ./hyprtabs # 10 windows in workspace, 122 commands to IPC! Benchmark 1: ./hyprtabs Time (mean ± σ): 12.0 ms ± 4.7 ms [User: 0.9 ms, System: 3.4 ms] Range (min … max): 4.4 ms … 20.0 ms 490 runs $ hyperfine -N ./hyprtabs # 20 windows in workspace, 242 commands to IPC!! Benchmark 1: ./hyprtabs Time (mean ± σ): 24.0 ms ± 10.9 ms [User: 0.9 ms, System: 3.3 ms] Range (min … max): 9.0 ms … 44.4 ms 77 runs
Compare the results above with the original
hyprtabs.sh
:$ hyperfine ./hyprtabs.sh # 1 window in workspace Benchmark 1: ./hyprtabs.sh Time (mean ± σ): 103.0 ms ± 8.1 ms [User: 51.6 ms, System: 88.1 ms] Range (min … max): 92.6 ms … 122.3 ms 30 runs $ hyperfine ./hyprtabs.sh # 10 windows in workspace Benchmark 1: ./hyprtabs.sh Time (mean ± σ): 115.5 ms ± 9.6 ms [User: 50.2 ms, System: 85.8 ms] Range (min … max): 94.8 ms … 136.8 ms 28 runs $ hyperfine ./hyprtabs.sh # 20 windows in workspace Benchmark 1: ./hyprtabs.sh Time (mean ± σ): 121.5 ms ± 5.8 ms [User: 50.7 ms, System: 82.4 ms] Range (min … max): 112.6 ms … 133.6 ms 23 runs
-
Zero dependencies: smaller binary sizes
- Dispatchers: for
calling dispatchers, batch mode supported, e.g.:
c.Dispatch("exec kitty", "exec firefox")
- Keywords: for dealing with
configuration options, e.g.: (
c.SetKeyword("bind SUPER,Q,exec,firefox", "general:border_size 1")
) - Hyprctl commands:
most commands are supported, e.g.:
c.SetCursor("Adwaita", 32)
.- Commands that returns a JSON in
hyprctl -j
will return a proper struct, e.g.:c.ActiveWorkspace().Monitor
- Commands that returns a JSON in
- Raw IPC commands:: while not recommended
for general usage, sending commands directly to the IPC socket of Hyprland is
supported for i.e.: performance, e.g.:
c.RawRequest("[[BATCH]] dispatch exec kitty, keyword general:border_size 1")
- Events: to subscribe and handle Hyprland events, see events for an example on how to use it.
If you are developing inside a Hyprland session, and have Go installed, you can simply run:
# -short flag is recommended otherwise this will run some possibly dangerous tests, like TestKill()
go test -short -v
Keep in mind that this will probably mess your current session. We will reload your configuration at the end, but any dynamic configuration will be lost.
We also have tests running in CI based in a NixOS VM
using nixosTests
. Check the
flake.nix
file. This will automatically start a VM running
Hyprland and run the Go tests inside it.
To run the NixOS tests locally, install Nix in any Linux system and run:
nix --experimental-features 'nix-command flakes' flake check -L
If you want to debug tests, it is possible to run the VM in interactive mode by running:
nix --experimental-features 'nix-command flakes' build .#checks.x86-64_linux.testVm.driverInteractive
./result
And you can run start_all()
to start the VM.
- hyprland-ipc-client for inspiration.