Waybar Peek

A lightweight Python utility that automatically shows/hides Waybar in Hyprland based on cursor position and window state.

Features

• Auto-hide: Waybar hides when windows are open on the workspace
• Peek on hover: Move cursor to top edge to reveal the bar
• Toggle on/off: Keybind to enable/disable auto-hide
• Multi-monitor support: Works correctly across multiple displays
• Lightweight: Pure Python, no external dependencies (~14MB RAM, 0% CPU)
• Hyprland native: Communicates directly via Hyprland's Unix socket

Resource Usage

Minimal footprint - runs efficiently in the background:

How It Works

1. When a workspace has no windows, the bar stays visible
2. When windows are open, the bar hides automatically
3. Move your cursor to the top edge of any monitor to reveal the bar
4. The bar hides again when cursor moves away (below 50px threshold)

Requirements

• Hyprland
• Waybar
• Python 3.6+

Installation

Option 1: Copy the script

# Clone or download
git clone https://github.com/waliori/waybar-peek.git
cd waybar-peek

# Copy to your Hyprland scripts
cp waybar_peek.py ~/.config/hypr/scripts/
chmod +x ~/.config/hypr/scripts/waybar_peek.py

Option 2: Run from anywhere

chmod +x waybar_peek.py
# Add to your PATH or run directly

Waybar Configuration

Add these lines to your Waybar config (~/.config/waybar/config):

{
    "start_hidden": true,
    "ipc": true,
    "on-sigusr1": "hide",
    "on-sigusr2": "show",
    // ... rest of your config
}

Hyprland Configuration

Add to your hyprland.conf or exec.conf:

exec-once = ~/.config/hypr/scripts/waybar_peek.py &

Configuration

Edit the constants at the top of waybar_peek.py:

PIXEL_THRESHOLD = 5          # Pixels from top to trigger show (default: 5)
PIXEL_THRESHOLD_HIDE = 50    # Pixels to move down before hiding (default: 50)
POLL_INTERVAL = 0.1          # Polling interval in seconds (default: 0.1)

Toggle Auto-Hide

Toggle auto-hide on/off with SIGHUP:

pkill -HUP -f waybar_peek   # Toggle auto-hide on/off

When disabled, the bar stays permanently visible.

Hyprland Keybind

Add to your hyprland.conf or keybinds.conf:

# Toggle waybar auto-hide
bind = SUPERSHIFT, W, exec, pkill -HUP -f waybar_peek

Manual Control

You can manually show/hide waybar with signals:

pkill -USR2 waybar   # Show the bar
pkill -USR1 waybar   # Hide the bar

Troubleshooting

Bar doesn't appear when moving to top

• Ensure HYPRLAND_INSTANCE_SIGNATURE environment variable is set
• Check if the script is running: pgrep -f waybar_peek
• Verify waybar has start_hidden and signal handlers configured

Script won't start

• Check Python version: python3 --version (needs 3.6+)
• Ensure script is executable: chmod +x waybar_peek.py

License

MIT License

Credits

Inspired by waybar_auto_hide (Rust implementation).