Omalaunch

An extensible command launcher for Omarchy.

Omalaunch keeps the familiar Omarchy command tree while adding fast global search, application results, favorites, usage-aware ranking, calculations and conversions, and independently installable extensions.

Installation

From the Omarchy menu

1. Open Setup › Plugins › Add Plugin.
2. Enter https://github.com/daniellemky/omalaunch as the Git URL.
3. Review and confirm Omarchy’s plugin trust warning.
4. Confirm that you want to enable Omalaunch.
5. Choose left when prompted for a bar section.

From a terminal

omarchy plugin add https://github.com/daniellemky/omalaunch --enable

Review and confirm the plugin trust warning, then choose left when prompted for a bar section.

Enabling Omalaunch replaces Omarchy’s default clickable launcher icon and routes the existing Super+Space shortcut to Omalaunch. Disabling or removing the plugin restores the default Omarchy launcher. No calculation dependency needs to be installed before adding the plugin; Omalaunch offers explicit setup from its starting view when needed.

Click the launcher icon or press Super+Space to open Omalaunch. Right-clicking the icon opens a terminal.

Current Omarchy versions can select a bar section during installation but not an exact index. If the launcher icon appears after the workspace buttons, move it to the first position with:

omarchy bar move quantumfire.omalaunch --section left --index 0

This workaround can be removed once Omarchy supports setting a widget’s section and index during plugin installation.

Features

• Search the complete Omarchy command tree and installed applications
• Star favorites and rank frequently used results
• Run arithmetic, unit conversions, and currency conversions with qalc
• Copy calculation results directly to the clipboard
• Browse, recursively search, open, copy paths, and star local files and directories
• Look up current times and convert times across DST-aware timezones
• Search with Google, DuckDuckGo, Bing, Brave Search, or Ecosia
• Accept dmenu-style select and input requests
• Close the launcher by clicking outside it on any monitor
• Load extensions contributed by enabled Omarchy plugins
• Launch agent prompts such as Pi and Codex through optional extensions

Starred favorites

Star frequently used applications, commands, files, directories, and extension shortcuts on the launcher’s starting view. Matching starred items rank above unstarred search results, and starred files and directories are searchable by name or path-component prefix. Search then ranks by text-match quality, usage count, recent use, and a stable fallback. Exact aliases and title substring matches share one tier, so usage decides between them. Exact titles and title prefixes remain higher tiers, and result type does not change the text-match tier.

Calculator

Evaluate arithmetic, units, and currency conversions without leaving the launcher. Press Enter to copy the result. With NumLock on, you can use the numeric keypad to enter digits, operators, and decimal points.

Currency conversion

Convert currencies inline using qalc exchange-rate data. Press Enter to copy the result.

Timezones

Type time to select the bundled Timezone extension. Look up the current time with queries such as time seattle or convert a specific time with time 9am winnipeg to tokyo. Dates are optional, city aliases and IANA timezone names are supported, and conversions account for daylight-saving time.

time seattle
time 9am winnipeg to tokyo
time 2026-11-15 8pm new york to london

Web Search

Open Web Search, select a search engine, enter a query, and press Enter. Omalaunch opens the encoded search in your default browser. Each engine can be added to or removed from global search while it remains available in the Web Search menu. Press Ctrl+S to star an engine on the launcher's starting view. Press Ctrl+, in Web Search to create and edit ~/.config/omarchy/omalaunch/extensions/omalaunch.web-search.jsonc with the default editor or coding agent. Add, replace, or remove engines there; see PROVIDER-CONFIGURATION.md.

Files

Type files and activate the Files result to browse from your home directory. Select folders to navigate, type to search recursively within the current folder, and select a file to open it with the default application. Supported image files show thumbnails in the result list and a larger preview pane when selected. Directory contents are ordered by most recently modified, while search uses fd with fzf's path-aware relevance ranking. A short-lived per-directory index is reused while typing so each query does not traverse the filesystem again. Hidden and ignored files are excluded.

Press Ctrl+K on a selected item to open its Action Panel. Directories can be opened in Files or a terminal, while files can be opened with their default application. Files and directories can also be starred for the launcher’s starting view from the Action Panel or directly with Ctrl+S. Every item supports copying its path or copying the item to the file clipboard. Ctrl+C remains a shortcut for copying the selected path.

Requirements

• A current Omarchy installation with the manifest-based shell plugin system
• libqalculate (qalc) to enable calculations and conversions
• fd, fzf, jq, Python 3, Bash, and wl-clipboard (provided by a standard Omarchy installation; Python drives extension loading and file indexing)

Install the calculation dependency through Omarchy:

omarchy pkg add libqalculate

If it is missing, the launcher’s starting view shows Enable Calculator & Currency. Press Enter to review the exact command and explicitly confirm opening it in a visible terminal. The same setup remains available from unavailable calculation results. Reopen Omalaunch afterward to recheck the dependency; no shell restart is required. All unrelated launcher features remain usable.

Omalaunch never installs system packages silently. Package installation is offered only for dependencies allow-listed by Omalaunch itself; external extensions cannot supply installation commands.

Application library compatibility

Omalaunch uses Omarchy's shared application library when it is available. If the shell omits that library, as can occur on Omarchy 4.0.3, Omalaunch uses a separate instance of the installed application service. This preserves Omarchy's application filtering, icons, and launch behavior without changing system files. The separate instance is released when the shared library becomes available. If the installed service is missing or cannot load, application results remain unavailable; other menu commands still work.

Icon refresh supports both the original application service and the newer scoped API. On the scoped API, refresh requests use a 30-second interval without waiting for an unavailable completion signal.

Usage

Start typing to search commands and applications. Use the arrow keys or Tab and Shift+Tab to move, Enter to activate, and Escape to go back or close the launcher.

Examples:

10 USD to CAD
25 * 4
browser
wifi
files

Calculation results appear first and are copied to the clipboard when activated.

Extensions

Open the fixed top-level Extensions directory to find every active bundled and external extension, including Calculator, Currency conversion, Files, Timezone, Web Search, and installed workflow integrations such as Codex. Select Add Extension to browse the extension marketplace, install an extension from a Git repository URL, or create an extension with your default coding agent. Omalaunch creates a minimal extension plugin under ~/.config/omarchy/plugins/<username>.<extension-slug>/ by default, where Omarchy discovers it. Set extensionDevelopmentDirectory in ~/.config/omarchy/omalaunch/config.jsonc to use another location. Star an extension with Ctrl+S to add the same shortcut to the starting view; it remains in Extensions, where starred shortcuts sort first and all others sort alphabetically. The directory itself cannot be starred. Global search finds extension shortcuts whether or not they are starred.

Shortcut activation follows the extension type: Files opens its browser, Timezone prepares its prefix, Calculator and Currency conversion open focused query input, and workflow extensions open their workflow. A replacement provider supplies the capability shortcut, but it does not inherit the original provider's favorite because stored ownership uses the exact provider ID. Missing dependencies are shown on the shortcut without affecting unrelated extensions.

Omalaunch includes replaceable bundled extensions. Every external Omalaunch extension is simply a standard Omarchy plugin, so it uses the same installation, enable/disable, update, and removal workflow as any other Omarchy plugin.

Install an extension directly from its repository:

omarchy plugin add https://github.com/example/omalaunch-example --enable

Once enabled, Omalaunch discovers it automatically through the plugin manifest:

"omalaunch": {
  "extensions": ["omalaunch.json"]
}

Browse available integrations in the Omalaunch Extension Directory. Each extension repository contains its exact installation command. See EXTENSIONS.md for the complete extension contract and examples.

Configuration

Omalaunch reads the stock Omarchy menu and the standard user menu override:

~/.config/omarchy/extensions/omarchy-menu.jsonc

Favorites and usage data are stored in the user's state directory. Currency refreshes use qalc and respect a persistent cooldown to avoid unnecessary network requests.

Omalaunch core settings live in the dedicated ~/.config/omarchy/omalaunch/config.jsonc file. Select a preferred extension provider by capability:

{
  "version": 1,
  // Theme class for primary menu item text.
  "menuItemFontClass": "title",
  // Optional explicit override. Valid range: 8–24 pixels.
  // "menuItemFontSize": 15,
  "capabilities": {
    "files": { "provider": "omalaunch.files" },
  },
}

menuItemFontClass accepts caption, bodySmall, body, subtitle, title, heading, display, or displayLarge. It defaults to title. If menuItemFontSize is set, its explicit pixel size takes priority over the theme class.

Press Ctrl+, in Omalaunch to open Omalaunch Settings. The Font Size menu provides Compact, Small, Default, Large, and Extra Large theme-aware presets. Selecting a preset removes an explicit menuItemFontSize override so the chosen theme class can take effect.

Quicklinks and Web Search show a Settings · Ctrl+, footer action that can create and open their JSONC file with the default editor or coding agent. Bundled provider settings use provider-ID JSONC files under the configuration directory. Interactive data uses provider-ID JSON state under ${XDG_STATE_HOME:-~/.local/state}. Replacement providers do not inherit either namespace. See PROVIDER-CONFIGURATION.md for the separate configuration and state schemas, supported versions, and migration rules. Quicklinks does not import external or unreleased data.

If a preferred provider is missing or unavailable, Omalaunch reports a diagnostic and uses its normal provider selection rules.

Updating

omarchy plugin update quantumfire.omalaunch --yes
omarchy restart shell

The --yes flag skips the interactive diff review; omit it if you prefer to review and confirm every incoming change. Restart the shell after updating so the running QML engine does not continue using cached plugin code. This works around an upstream Omarchy hot-reload issue until plugin rescans reliably load changed QML. The restart reloads Omalaunch code and is unrelated to calculation dependencies; installing libqalculate requires only reopening Omalaunch to recheck it.

Disabling and removal

Disable or re-enable Omalaunch without removing it:

omarchy plugin disable quantumfire.omalaunch
omarchy plugin enable quantumfire.omalaunch

Remove it completely:

omarchy plugin remove quantumfire.omalaunch

Disabling or removing Omalaunch restores the stock launcher. Removing Omalaunch does not remove its optional extension plugins, saved state, or system dependencies.

Security

Omarchy plugins are unsandboxed and run with the current user's permissions. Install plugins only from sources you trust.

Omalaunch executes commands supplied by the stock menu, user menu configuration, and enabled extension plugins. Extension commands are represented as argument arrays; Omalaunch substitutes the prompt and shell-quotes each argument. Dependency installation is never performed silently.

Currency conversion may cause qalc to retrieve updated exchange-rate data from its configured upstream source.

Development

Run the tests with:

node tests/menu-model-test.js
bash tests/manifest-test.sh
bash tests/qalc-integration-test.sh
bash tests/timezone-integration-test.sh
python tests/file-index-integration-test.py

The integration test requires qalc.

Release maintainers should follow RELEASING.md. Omarchy updates plugins from the default branch, so master remains stable while version tags and GitHub releases provide immutable reference and rollback points.

Acknowledgements

Omalaunch began as a customization of Omarchy's built-in menu and continues to consume Omarchy's standard menu definitions and shell APIs.

License

MIT © Daniel Lemky