Omarchy Background Listener

Overview

This repository contains the Hyprland event listener script that drives workspace-aware wallpapers for the Omarchy desktop (an Arch Linux derivative). The script listens for monitor and workspace events and swaps backgrounds via swww so each workspace can have its own image.

Out of the box the wallpaper mapping targets the Matt Black theme. The listener is intentionally minimal and assumes a single theme directory of wallpapers, so treat it as a starting point that you can adapt to match the structure of your own Omarchy setup.

Requirements

All commands below assume an Arch-based system with the yay AUR helper installed.

swww

Fast wallpaper switcher used to display images and (eventually) pre-cache them.

yay -S --needed swww

swww-daemon

Maintains compositor state for swww so image transitions are smooth. This package currently lives in the AUR.

yay -S --needed swww-daemon

socat

Streams Hyprland events from the UNIX socket into the listener script.

yay -S --needed socat

ℹ️ The script also expects Hyprland's hyprctl binary and jq (both part of a standard Omarchy/Hyprland install).

Setup

1. Copy omarchy-background-listener.sh somewhere in your $PATH (for example, ~/.config/omarchy/bin/).
2. Make it executable:

   chmod +x ~/.config/omarchy/bin/omarchy-background-listener.sh

3. Place your wallpapers under ~/Pictures/wallpapers/ or adjust the WS_IMG map in the script to point to your preferred locations.
4. Ensure swww-daemon is running before starting the listener:

   swww-daemon &
   ~/.config/omarchy/bin/omarchy-background-listener.sh &

Omarchy autostart.conf

Add the following lines to your ~/.config/omarchy/autostart.conf so the daemon and listener start with Hyprland (update paths if you put the script elsewhere):

exec-once = swww-daemon
exec-once = ~/.config/omarchy/bin/omarchy-background-listener.sh

Comment out the default sway background line, as the listener now controls backgrounds:

# exec-once = uwsm app -- swaybg -i ~/.config/omarchy/current/background -m fill

Restart Hyprland or reload the config to activate the changes.

Customization & Future Work

• Replace the entries in WS_IMG with images that match your workspace layout or, better yet, refactor the script to load mappings from a config file so it can support multiple themes beyond the current Matt Black setup.
• The move to swww was motivated by its ability to pre-cache images for buttery transitions—precaching hooks have not been added yet, so contributions in that direction are welcome.
• Per-monitor defaults, named workspaces, and theme profiles are all areas ready for improvement.

Warranty & Support

This code is provided as-is, with no formal support. Review the script, adapt it to your environment, and test changes carefully before relying on it in production sessions.