Desktop Command Wrappers

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:

Mode	Behaviour
--shell	Default. Run the command, then stay in an interactive shell.
--wait	Run the command, then print a prompt saying Ctrl-D closes or the shell can continue.
--exit	Run the command and close the terminal when it exits.

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.

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.

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