Omascope

A fast, theme-aware command palette for Omarchy Quattro.

Omascope replaces the stock Omarchy menu with forgiving fuzzy search, useful keyboard hints, usage-aware ranking, and instant calculations—while preserving the active Omarchy theme and the menu structure you already know.

Omascope is currently an early release. It is tested against Omarchy 4.0.0-1 and includes a guarded migration tool for later menu updates.

Highlights

• Fzf-style subsequence matching: frfx finds Firefox.
• Typo tolerance: firfox, firefix, and fierfox still find Firefox.
• Unified search across applications, commands, submenus, aliases, and descriptions.
• Deterministic ranking with private, local usage-based tie-breaking.
• Theme-aware colors, icons, borders, scrim, and selection states.
• Compact, context-aware keyboard hints for Open, Run, Copy, and Uninstall.
• Arithmetic, percentages, unit conversions, and currency conversions powered by the locally installed qalc.
• Safe upstream migration with change detection, three-way merging, validation, and rollback before touching the live launcher.

Install

Omascope requires Omarchy Quattro. Its runtime tools—qalc for calculations and wl-copy for clipboard output—are included in a standard Omarchy install. If either tool is absent, install the corresponding libqalculate or wl-clipboard package using Omarchy's package-management tools.

Omascope checks both tools at shell startup. A missing calculator produces an actionable setup row; a missing clipboard tool leaves answers visible and disables the Copy action instead of failing silently.

omarchy plugin add https://github.com/kailbert/omarchy-plugin-omascope.git --enable

The plugin deliberately declares omarchy.clonedFrom: "omarchy.menu". Omarchy therefore routes the existing Super+Space shortcut and omarchy.menu IPC calls to Omascope. Removing or disabling Omascope restores the stock menu.

Use

Press Super+Space and start typing. Literal matches rank first, followed by prefix, substring, subsequence, and conservative typo matches.

Omascope also recognizes clear calculations and conversions:

Query	Action
2 + 2	Calculate arithmetic
15% of 200	Calculate a percentage
10 km to mi	Convert units
12 euro in dollar	Convert conversational currency names
100 USD to EUR	Convert ISO currency codes
=sqrt(81)	Explicitly invoke the calculator

Instant answers appear above ordinary menu matches. Press Enter to copy the selected answer and close the launcher. Currency-rate refreshes happen in the background; cached rates provide the immediate result.

Keyboard

Key	Behavior
Enter	Open, run, select, or copy the highlighted result
Delete	Uninstall the highlighted application after confirmation
Up / Down	Move through results
Page Up / Page Down	Move by six results
Escape	Clear the query, then close the launcher
Backspace / Left	Return from a submenu when the query is empty

Updates and migration

Omarchy updates can change the built-in menu. Omascope adds an Update → Fuzzy Launcher action that checks the installed Omarchy menu against its recorded baseline. When changes exist, it performs a three-way merge in a temporary directory, validates the result, and only then deploys it.

For manual inspection:

npm run upstream:check
npm run upstream:migrate

Use npm run upstream:migrate:live only from a clean checkout whose files match the installed plugin. See UPSTREAM.md for conflict and rollback behavior.

Privacy and security

Omascope runs inside the unsandboxed Omarchy shell with your user permissions, as all Quattro plugins do. Review the source before enabling it.

• Search and usage history stay on the machine.
• Usage data contains only plugin entry IDs, counts, and timestamps at ~/.local/state/omarchy/fuzzy-menu-usage.json.
• Calculator input is passed directly to qalc as an argument array, never interpolated into a shell command.
• Currency conversion may let qalc refresh its exchange-rate data in the background.
• Omascope does not include telemetry or an online service.

Remove

omarchy plugin remove kailbert.omascope

Omarchy restores the built-in menu automatically. Local usage history can be removed separately if you no longer want it:

rm ~/.local/state/omarchy/fuzzy-menu-usage.json

Development

The UI lives in Menu.qml; the pure search model and instant-provider model are kept in JavaScript so they can be tested without launching Quickshell.

npm test
npm run benchmark
qmllint -I "$OMARCHY_PATH/shell" Menu.qml BarWidget.qml
omarchy plugin validate .

The automated suite covers fuzzy ranking, typo boundaries, usage ranking, calculator intent and normalization, safe result construction, and upstream three-way merges. The 2,000-entry benchmark enforces a worst average rebuild below 16 ms on the development machine.

Architecture and maintenance references:

• CHANGELOG.md — release history.
• PROVIDERS.md — instant-provider contract and lifecycle.
• UPSTREAM.md — update detection and guarded migration.
• PLAN.md — original MVP specification and acceptance criteria.

Roadmap

• Actions submenu for context-specific secondary commands.
• More instant providers built on the cancellable provider pipeline.
• Explicit integration with the user-selected Omarchy AI assistant, with clear privacy and timeout behavior.
• Marketplace preview media and final submission to Omarchy Plugins.

License

MIT. Omascope began as a user-owned clone of Omarchy's MIT-licensed menu plugin and retains attribution to its upstream authors.