hyprexpose

KO | EN

gitlite — search

#javascript #react #ai #typescript #llm #android #rust #deep-learning #linux #awesome #vue #awesome-list #ios #open-source

(★ 10)

Lightweight workspace overview for hyprland. Shows active workspaces with real window thumbnails, navigate with keyboard, press Enter to switch.

hyprexpose Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# hyprexpose

[![AUR](https://img.shields.io/aur/version/hyprexpose-git)](https://aur.archlinux.org/packages/hyprexpose-git)
![vibecoded](https://img.shields.io/badge/vibecoded-ff69b4?style=flat&logo=sparkles&logoColor=white)

Lightweight workspace overview for [Hyprland](https://hyprland.org) and [Sway](https://swaywm.org). Shows active workspaces with real window thumbnails, navigate with keyboard, press Enter to switch.

> **Requires Hyprland >= 0.55** (uses the Lua-based IPC dispatch introduced in that release).

> **Sway support:** the compositor is auto-detected at startup (via `SWAYSOCK`). Window thumbnails require the `hyprland-toplevel-export` protocol, which Sway doesn't implement — on Sway, windows are drawn as colored rectangles with their app id instead (same as `--no-preview`). Everything else (grid, keyboard/mouse navigation, switching, moving windows) works the same.

![Demo](https://raw.githubusercontent.com/ThiagoAVicente/hyprexpose/master/demo.gif)

## Features

- Works on Hyprland and Sway (auto-detected)
- Real window thumbnails via hyprland-toplevel-export protocol (Hyprland only)
- Fullscreen overlay using wlr-layer-shell
- Keyboard navigation (arrow keys / hjkl)
- Move the active window to another workspace with `m`
- Runs as a daemon, toggled with SIGUSR1 (~0% CPU when hidden)
- Direct IPC via the compositor's unix socket (no process spawning)
- TOML config file for colors, fonts, and behavior

## Dependencies

**Build:** Rust toolchain (`cargo`), `libwayland-dev`, `libpango1.0-dev`

On Arch:

```
pacman -S rust wayland pango
```

On Ubuntu/Debian:

```
apt install cargo libwayland-dev libpango1.0-dev
```

## Build

```
cargo build --release
```

The binary is at `target/release/hyprexpose`.

## Usage

Start the daemon:

```
hyprexpose &
```

Disable window previews (uses colored rectangles instead):

```
hyprexpose --no-preview &
```

Enable mouse navigation (hover to select, left-click to switch, right-click to move active window):

```
hyprexpose --allow-mouse &
```

Flags can be combined: `hyprexpose --no-preview --allow-mouse &`.

Toggle the overlay:

```
pkill -SIGUSR1 hyprexpose
```

Add to your Hyprland config:

```ini
exec-once = hyprexpose
bind = $mainMod, Tab, exec, pkill -SIGUSR1 hyprexpose
```

Or to your Sway config:

```
exec hyprexpose
bindsym $mod+Tab exec pkill -SIGUSR1 hyprexpose
```

## Install (AUR)

```
yay -S hyprexpose-git
```

## Controls

| Key | Action |
|---|---|
| Arrow keys / hjkl | Navigate workspaces |
| Enter | Switch to selected workspace |
| `m` | Move active window to selected workspace |
| Escape | Close overlay |

## Configuration

Copy the example config and edit to taste:

```
mkdir -p ~/.config/hyprexpose
cp config.example.toml ~/.config/hyprexpose/config.toml
```

Config is loaded from `$XDG_CONFIG_HOME/hyprexpose/config.toml` (falls back to `~/.config/hyprexpose/config.toml`). All fields are optional — defaults are used for anything not specified.

See [`config.example.toml`](config.example.toml) for all available options with inline documentation.

## How it works

hyprexpose runs as a background daemon that does nothing until it receives SIGUSR1. On signal, it:

1. Queries the compositor's IPC socket for active workspaces and clients (Hyprland socket or i3-ipc on Sway)
2. Captures window thumbnails via the hyprland-toplevel-export protocol (Hyprland only)
3. Renders workspace cards with Cairo/Pango onto a wlr-layer-shell overlay
4. Waits for keyboard input, then switches workspace (or moves a window) and hides

## License

MIT

hyprexpose

hyprexpose Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

hyprexpose

hyprexpose Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README