SuperRun

A Run box for everything on PATH. Press the key, type a command, press Enter.

It started as a keybinding: SUPER + R opening a terminal that ran compgen -c | fzf. That worked, and it cost a terminal window, a window rule to keep it from tiling, and a shell to start before you could type the first letter. This is the same idea with the terminal taken out of the middle.

It deliberately does not list applications. SUPER + SPACE already does that, with names and icons. This lists what is on PATH — the half a launcher usually cannot reach.

Install

omarchy plugin add https://github.com/chameleonbr/omarchy_superrun.git --enable --yes

Then bind it. In ~/.config/hypr/bindings.lua:

o.bind("SUPER + R", "Run", "omarchy-shell shell toggle avila.superrun")

The plugin claims no keybinding of its own — that is the compositor's to give.

Keys

The top match is highlighted as soon as there is one, so four letters and Enter run the command rather than the four letters. When nothing matches, nothing is highlighted and Enter runs the line exactly as typed — which is how a full path, or a one-off with no command of its own, still works.

Arguments survive either way: ffm -i in.mp4 with ffmpeg highlighted runs ffmpeg -i in.mp4, and code ~/notes runs as written.

Commands that need a terminal

A command launched from here has no terminal: no output, no prompt, no exit code, nowhere for sudo to ask for a password. That is right for firefox and wrong for htop.

Start the line with ! and it gets a window:

!htop
!pacman -Syu
!journalctl -u foo -n 50

The window stays open after the command exits and shows its exit code — a command that fails in a tenth of a second is the reason you asked for a window in the first place. Press Enter to close it.

The terminal is $TERMINAL if it is set, then xdg-terminal-exec (which asks the desktop which terminal you actually chose), then whichever of alacritty, ghostty, kitty, foot, wezterm or xterm is installed.

The ! is a prefix, not part of the command: !hto still finds htop, Tab still completes it, and the ! is still there afterwards.

When it will not run something

Enter checks that the command resolves before the box closes. If it does not, the box stays open and says why:

nosuchcmd123: not on PATH
~/Apps/Foo.AppImage: no such file
~/Apps/Foo.AppImage: not executable — chmod +x it

This exists because the alternative is silence. A detached process has no exit code to report, so a typo used to close the box and open nothing, which reads as a launcher that does not launch.

It is one question — does the name resolve — not a guarantee the command will succeed. A name the shell would have to build first ($(…), backticks, quotes, a glob) is not checked at all: guessing wrong there would refuse a launch that would have worked, which is a worse failure than the one being fixed.

Relative paths are worth knowing about: ./foo.AppImage resolves against the shell process's working directory, not yours. Use ~/ or a full path.

How it matches

Four bands, and they never overlap: an exact name beats every prefix, a prefix beats every substring, a substring beats every subsequence. Inside a band the shorter name wins, because a short name that contains what you typed is more likely to be the one you meant.

Subsequence is what makes gtk3d find gtk3-demo. With nothing typed the list is alphabetical — ranking by length there would fill the top of an untouched list with w, [ and du.

What it runs

The line goes to sh -c, so ~, quotes, pipes and redirections mean what they look like they mean. Where uwsm-app exists the process is launched through it, so it lands in the session's app slice and does not die with whatever spawned it; where it does not, the command still runs.

The list itself is a PATH scan — every regular, executable file one level deep in each PATH entry, symlinks followed, duplicates collapsed. Not compgen -c: that also answers with builtins, aliases and functions, none of which can be launched as a process, and offering a row that does nothing when chosen is worse than not offering it.

PATH is scanned each time the box opens rather than cached, because something you just installed is exactly what you are most likely to reach for.

Development

node test_superrun.js     # 27 checks, no compositor, no shell, no PATH of its own
omarchy plugin validate .

Everything decidable without a screen lives in SuperRun.js — what counts as a command, how a query scores against one, and what actually gets executed — so the checks are all pure functions fed a list.

License

MIT.