https://github.com/vncsmyrnk/gwin
A "Run or raise" CLI tool for Wayland GNOME.
https://github.com/vncsmyrnk/gwin
dbus gio gnome rofi window-calls
Last synced: 25 days ago
JSON representation
A "Run or raise" CLI tool for Wayland GNOME.
- Host: GitHub
- URL: https://github.com/vncsmyrnk/gwin
- Owner: vncsmyrnk
- License: gpl-3.0
- Created: 2026-04-01T19:52:09.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-05-01T18:59:32.000Z (about 2 months ago)
- Last Synced: 2026-05-01T20:23:58.379Z (about 2 months ago)
- Topics: dbus, gio, gnome, rofi, window-calls
- Language: Zig
- Homepage:
- Size: 84 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://wiki.archlinux.org/title/GNOME)
[%22&replace=%241&style=plastic&logo=zig&label=Zig&color=F7A41D)](https://ziglang.org/)
[](https://aur.archlinux.org/packages/gwin-git)
[](https://repo.fury.io/vncsmyrnk/)
[](https://github.com/vncsmyrnk/gwin/actions/workflows/ci-cd.yml)
[](https://github.com/vncsmyrnk/gwin/issues)
# gwin
A "Run or raise" CLI tool for Wayland GNOME, leveraging the [window-calls extension](https://github.com/ickyicky/window-calls) D-Bus interface for opened windows.
## Context
GNOME's Wayland implementation does not support native ways to securely access window lists due to security risks. If you want to use a custom _dmenu_ tool or have special bindings for switching between opened windows, the only solution to achieve this until now is using Mutter to fetch the windows state via an extension.
Fortunately, this extension already exists: [window-calls extension](https://github.com/ickyicky/window-calls). It also export this state over D-Bus, making it possible to view and manipulate it.
## Goal
This project aims to provide ways to open currently opened instances or launch new ones when there is no instance already opened. GNOME's default finder already achieves this but offers minimal customization and GNOME itself does not offer native ways to use external _dmenus_ like `rofi`.
The primary goal is to provide useful, predefined and optimized use cases for switching between opened windows via `window-calls` and its D-Bus interface, avoiding the overhead of connections and fragile parsing when using multi-purpose D-Bus tools like `bustcl`.
### Secondary goals
- Provide a list of opened windows and ways to switch to them via _dmenus_
- Provide a list of installed applications and ways to run or raise them via _dmenus_
> [!NOTE]
> **Why Zig?** It can directly import C bindings for GDBus, already included as part of GNOME project's GLib (`gio/gdbus`).
## Examples
### Switching to opening windows using `rofi`
```sh
gwin list windows --rofi | rofi -x11 -normal-window -dmenu | xargs -I{} gwin switch --id {}
```
### Running or raising applications using `rofi`
```sh
gwin list applications --rofi | rofi -x11 -normal-window -dmenu | xargs -I{} gwin raise {}
```
## Install
### AUR
Install it with your favorite AUR helper.
```sh
yay -S gwin-git
```
### APT (Debian and its derivatives)
```sh
echo "deb [trusted=yes] https://apt.fury.io/vncsmyrnk /" | sudo tee /etc/apt/sources.list.d/fury.list
sudo apt update && sudo apt install gwin
```
### From source
```sh
git clone git@github.com:vncsmyrnk/gwin.git
just build
./zig-out/bin/gwin
```
> [!IMPORTANT]
> Make sure to have the [window-calls extension](https://github.com/ickyicky/window-calls) installed before running `gwin`. Restart the GNOME session after installing the extension.
## Roadmap and new features
Check out [issues](https://github.com/vncsmyrnk/gwin/issues) for upcoming changes or bug fixes.