Desktop Command Wrappers

Small helper scripts for terminal launches, notifications, loading overlays, and workspace placement.

These wrappers make other scripts and Hypr bindings friendlier on the desktop. They are intentionally small, but they are useful when composing menu actions or one-shot helpers.

Run a command in a terminal

run-in-terminal opens a command in a new terminal window:

run-in-terminal 'dot doctor'

Modes:

Examples:

run-in-terminal --wait 'workspace-restore --dry-run'
run-in-terminal --exit 'dot doctor'

For --shell and --wait, the wrapper creates a temporary ZDOTDIR so the command runs after shell initialisation, then removes that temp directory from the generated shell startup file.

Notify around a command

run-with-notify runs a command and sends a desktop notification with the result:

run-with-notify 'Capture' workspace-capture
run-with-notify -a 'Workspace' 'Restore' workspace-restore

On success, the notification body is command output or Done. On failure, it sends a critical notification with the captured stderr/stdout or Unknown error. Both use Omarchy’s glyph and spacing format.

Loading overlay

popup-loading shows a singleton GTK layer-shell loading overlay on the focused Hyprland monitor:

popup-loading show 'Updating...'
popup-loading hide

Calling it with only a message also shows the overlay:

popup-loading 'Loading dashboard...'

The overlay keeps a runtime socket and lock under ${XDG_RUNTIME_DIR:-/tmp}:

popup-loading.sock
popup-loading.lock

It reads theme colours from:

~/.config/omarchy/current/theme/colors.toml

If theme colours are unavailable, it falls back to a dark default.

Wrap a command with the loading overlay

with-popup-loading shows the overlay, runs the command, then hides the overlay on exit:

with-popup-loading 'Updating dotfiles...' dot update

If no command is passed, it only shows the overlay and lets the shell trap hide it when the wrapper exits.

Launch on a workspace

launch-on-workspace starts a command, waits for a new Hyprland client matching a class regex, then moves that new window to the target workspace:

launch-on-workspace 3 '^(work-browser|google-chrome)$' 'uwsm app -- google-chrome-stable --new-window'

It compares matching client addresses before and after launch. Only a newly detected address is moved.

This helper is used by the work browser launchers documented in Work Browser Launchers.

Toggle HDR on the primary monitor

toggle-primary-monitor-hdr temporarily enables 10-bit HDR with the full BT.2020 colour gamut and raises SDR content brightness through Hyprland’s sdrbrightness setting (currently 2.0):

toggle-primary-monitor-hdr

On the desktop host it targets the main HDMI-A-2 display, preserving the original right-monitor behaviour. On other hosts it targets the focused display, using its live resolution, refresh rate, position, scale, and transform.

Run it again while HDR is active to restore 8-bit SDR colour and normal SDR brightness. Both rules are applied at runtime and are not written to monitors.conf.

Troubleshooting

If run-in-terminal --exit closes too quickly, use --wait while debugging.

If popup-loading fails to show, check that the session supports GTK4 layer shell and that hyprctl -j monitors works.

If launch-on-workspace launches the app but does not move it, the class regex probably does not match the final Hyprland class. Inspect clients with:

hyprctl -j clients