instantMENU

General purpose menu for instantOS

instantMENU is a simple menu for instantOS it is used for instantASSIST and in some other places

Installation from source

git clone https://github.com/instantOS/instantMENU
cd instantMENU
cargo build --locked
# Or install the debug build and helper scripts for your user:
just install

Release archives, Arch Linux packages, and Debian packages are also attached to each GitHub release.

Releases

The version-bump workflow opens a release/version-bump pull request using conventional commits to choose the next version. Merging that PR creates the matching v* tag and publishes the release artifacts. A patch, minor, or major bump can also be selected manually from the workflow dispatch form.

Features

• alt-tab switcher mode: cycle with Alt+Tab, release Alt to pick (--alt-tab)
• mouse support
• animations and hover over indicators
• composable item metadata for icons, colors, headings, hidden match terms, and single-key menus
• slider mode (instantmenu slide 'brightnessctl s')
• streamed input: the menu opens instantly and items appear as stdin produces them
• Catppuccin, classic and Gruvbox themes (--theme)

Large fuzzy searches update results progressively while the menu remains interactive. Small searches finish inline; a background worker starts only when a search exhausts its event-loop time budget. An ellipsis in the match counter means the result list is still being searched; ranking can improve as more candidates are scored. Enter accepts the current selection, and Escape cancels immediately. New input replaces an unfinished query instead of queuing searches for every intermediate keystroke. Automatic selection follows the best result. Once you navigate or hover to choose a result, incoming items preserve that choice and keep it visible, including when input finishes. Editing the query selects the best match again.

Appearance configuration

instantmenu reads one optional file: $XDG_CONFIG_HOME/instantmenu/config.toml, or ~/.config/instantmenu/config.toml when XDG_CONFIG_HOME is unset. Use --config PATH to require another file, or --no-config to skip configuration. The file is deliberately limited to font and colors:

font = "Iosevka:size=13"
theme = "gruvbox" # catppuccin (default), classic, or gruvbox

[colors.normal]
foreground = "#EBDBB2"
background = "#282828"
detail = "#504945"

[colors.selected]
foreground = "#282828"
background = "#83A598"
detail = "#8EC07C"

Every scheme is named: normal, fade, highlight, hover, selected, output, green, yellow, and red; each accepts foreground, background, and detail. Unknown keys and invalid colors are errors. A configured theme is applied first, then configured colors, then command-line --theme and color overrides.

is this dmenu?

instantMENU started as a fork of dmenu and keeps the dmenu workflow (items on stdin, selection on stdout, full keyboard control), with all extra features optional. The command line uses modern long options (--width, --right-command, ...) with a few single-letter shortcuts (-i, -p, -l, ...) instead of dmenu's historical flags.

For agent guidance on scripting and item markup, run instantmenu skill (also available as instantmenu --skill). It prints a self-contained Markdown skill without opening a display.

Item metadata

Each input line is normally its visible label and selected output. A leading attribute block adds metadata without becoming part of either:

Display
{blue icon=display match="monitor screen"} Display
{heading green} System actions
{red icon=power key=q} Power off

Known color names may be bare ({red}) or explicit ({color=red}). Other attributes are icon, key, shortcut, match, value, and the heading flag. Quote values that contain spaces. Run with --single-key to show and activate only entries that have key=…. Prefix a literal markup-like label with an extra opening brace: {{red} literal displays {red} literal. Use value to set a different output from the display label: {value="file:/tmp/a b"} My File displays My File but prints file:/tmp/a b.

All item activation paths use that same output value: Enter, mouse clicks, numbered shortcuts, Alt release, single-key activation, auto-confirm, and bound commands. For example, {key=h value=sh} Help displays Help in a single-key menu but outputs sh. Ctrl-Enter/Ctrl-click accept without closing. Shift-Return explicitly submits the input text instead (unless --reject-no-match is set); Shift-click still accepts the clicked item. Tab completion and hover prompts continue to use display labels.

Per-entry keyboard shortcuts

Use shortcut=… in a regular menu to activate an entry directly while keeping its full label visible. Hints align to the right of each entry with a left separator, using symbols for Ctrl (⌃), Alt (⎇), Shift (⇧), and Super (⊞):

instantmenu -l 5 <<'MENU'
{icon=folder shortcut=super-o value=open} Open folder
{blue shortcut=ctrl-shift-e value=edit} Edit
{shortcut=f2 value=rename} Rename
MENU

Combine ctrl-, alt-, shift-, and super- in any order before a character, function key (f1–f35), or named key (space, enter, tab, backspace, delete, insert, left, right, up, down, home, end, page-up, page-down). Letter names ignore case; request Shift explicitly. Plain characters are allowed but take precedence over typing into the search field. Escape, Ctrl-C, Ctrl-G, and unmodified Enter/Tab remain reserved.

Shortcuts activate only entries in the current search results, including other pages. They print the entry's value= (or label) and close the menu. Use unique shortcuts; duplicates select the first matching entry in input order. Global --bind actions take precedence on conflicts. Headings cannot have shortcuts, and shortcuts are inactive in --single-key, input-only, password, and toast modes. {key=q} remains the separate single-character --single-key interface.

Testing

Run cargo test --all-targets for the unit and CLI tests. With sway and wtype installed, also run:

cargo build --bin instantmenu
python3 scripts/test-streaming-wayland.py

The interaction test starts an isolated headless compositor and checks selection, typing, and cancellation while producers continue writing to real pipes. It also types expensive queries after 50,000 streamed paths and after a complete corpus of 90,000 paths. It runs against the debug binary by default.

---

instantOS is still in early beta, contributions always welcome

Application launcher

Use ins launch from instantCLI for desktop application discovery, frecency, and terminal application launching. instantMENU renders the menu; instantCLI owns application and terminal execution.