h-corners

A lightweight standalone hot-corners tool for Labwc (Wayland), inspired by modern desktop workflows.

Currently it's a work in progress and will change frequently.

Features

• Dwell Time: Configurable wait time before a corner action triggers.
• Visual Feedback: A subtle “Wi-Fi-wave” style animation while hovering in a hot corner.
• Native Wayland Integration: Uses zwlr-layer-shell-v1 for precise trigger zone placement.
• Optional nsd Relay: Corner triggers can be forwarded to nsd over the local Unix Domain Socket instead of being executed directly by h-corners.
• Lightweight: Minimal Python application with a small runtime footprint.

Installation

1) System dependencies

You need at least:

• Python 3.11+
• venv + pip
• Cairo

Examples (optional):

# Debian/Ubuntu
sudo apt install python3 python3-venv python3-pip libcairo2

# Arch
sudo pacman -S python python-pip cairo

# Fedora
sudo dnf install python3 python3-pip cairo

2) Virtual environment and Python packages

cd ~/workset/h-corners
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

3) Wayland protocols (only if you want to regenerate them)

Generated files are already included in protocols/. Regenerate only when needed:

mkdir -p protocols

# Core / stable
python3 -m pywayland.scanner -o protocols wayland_xml/wayland.xml
python3 -m pywayland.scanner -o protocols /usr/share/wayland-protocols/stable/xdg-shell/xdg-shell.xml

# wlroots layer-shell
python3 -m pywayland.scanner -o protocols wayland_xml/wlr/unstable/wlr-layer-shell-unstable-v1.xml

4) Run

./venv/bin/python hcorners.py

Optional with detailed logs:

./venv/bin/python hcorners.py --verbose

Important config options in hcorners.conf:

• hit_size (Global): minimum effective corner size (more reliable detection with small size values)
• verbose (Global): detailed runtime logs without CLI flag
• [Daemon].enabled: relay corner triggers to nsd
• [Daemon].fallback_to_local_command: keep local execution as fallback when nsd is unavailable

Optional nsd relay

If you want nsd to receive hot-corner triggers, enable the [Daemon] section:

[Daemon]
enabled = true
socket_path = /tmp/nsd.sock
relay_action = hotcorner.trigger
fallback_to_local_command = true

When enabled, h-corners sends a JSON IPC command to nsd. If relay fails and fallback_to_local_command is true, the local corner command is executed as before.

Example relay message sent by h-corners:

{
  "src": "h-corners",
  "type": "command",
  "action": "hotcorner.trigger",
  "payload": {
    "corner": "top_left",
    "name": "TopLeft",
    "command": "notify-send \"h-corners\" \"TopLeft triggered\"",
    "dwell_time": 500,
    "triggered_at": 1711023030.123
  }
}

Minimal corner payload fields you can rely on in nsd handlers:

• payload.corner
• payload.name
• payload.command
• payload.triggered_at

Development

Local development workflow:

cd ~/workset/h-corners
source venv/bin/activate
pip install -r requirements.txt
python hcorners.py -c hcorners.conf -l startlog.txt --verbose

Useful checks:

python -m py_compile hcorners.py
python -c "import cairo, pywayland; print('deps ok')"
python -m pytest -q

Troubleshooting

• ModuleNotFoundError: No module named 'cairo'

  • Cause: Python dependency is missing in the active venv.
  • Fix: Activate the venv and run pip install -r requirements.txt again.

• Missing Wayland globals (e.g. wl_compositor, wl_shm, zwlr_layer_shell_v1)

  • Cause: The session is not compatible or does not provide a suitable wlroots/layer-shell stack.
  • Fix: Start in a Wayland session with layer-shell support (e.g. Labwc/Sway).

Quick Check

./venv/bin/python -V
./venv/bin/python -c "import cairo, pywayland; print('ok')"