Omarchy keybinding editor

Browse Hyprland shortcuts by category, change existing bindings, and create or delete bindings in an Omarchy-themed panel.

Version 0.3.0 targets Omarchy 4 with Lua-based Hyprland 0.56.2 and Quickshell 0.3.1. Older .conf-based setups are not supported. This is a community plugin, not an official Omarchy component.

Main Window

Browse categories in the left sidebar or use the warning button next to search to find shared shortcuts. The panel follows your Omarchy theme. This screenshot predates the Import and Export buttons.

What you can do

• Search descriptions, shortcuts, categories, commands, and source names.
• Change a shortcut while keeping its original action, or record the combination you want.
• Reset an Omarchy-provided binding to its system-default shortcut, action, behavior, and category.
• Create a shortcut for a shell command, or replace an existing action with a command.
• Set a category and common behavior flags such as repeat or on-release.
• Delete custom bindings, disable inherited bindings, and restore originals.
• See shared-shortcut warnings without being prevented from saving.
• Export your saved or staged keybind map and import app-created maps with Merge or Replace.

Open

Open the installed and enabled plugin with the command below. On first open, review the setup prompt and press Confirm. After setup, you can also find Keybinding editor in your application launcher.

omarchy-shell shell toggle firstpick.keybindings

1. Choose a category or search for a binding.
2. Click a binding, or choose New binding.
3. Choose Record shortcut, wait for Press your shortcut, then press and release the combination. You can also type a shortcut such as SUPER + SHIFT + K.
4. Choose Stage changes.
5. Review the staged changes, then choose Apply changes.

After staging, the main list keeps the binding selected, visible, and keyboard-focused instead of returning to the top. Filters are preserved unless they would hide the edited binding.

Nothing is applied until step 5. Deletion and Reset to system default also remain staged until Apply. The editor shows the default shortcut for Omarchy-provided bindings; user-created bindings have no system default. Reset removes this editor's overrides, not hand-authored changes elsewhere in your config. Shared shortcuts may run more than one action, and some existing overlaps are intentional.

While recording, bare Escape or Cancel recording cancels without changing the field. Modified Escape can be recorded. The recorder waits until keys are released and stops on timeout, lost inhibition, or close. It requests compositor shortcut inhibition, but reserved or inhibition-bypass shortcuts may still run. Do not record destructive shortcuts just to test the editor.

Only enter shell commands you trust. The editor never runs a binding command as a preview, but Hyprland runs it when its shortcut is triggered. Keeping the original action is the safest choice when you only want to move a shortcut.

Import and export maps

Maps contain your editor customizations and custom command bindings, not a complete copy of your desktop configuration. Only this app's .keymap.json files are supported, not arbitrary Lua or .conf files.

Both dialogs default to ~/.config/hypr/keybindings-editor/exports/, beside the saved keybindings. If you use a custom XDG_CONFIG_HOME, the folder follows that setting. The app creates it on the first successful export, not when browsing. Existing exports elsewhere are not moved.

Export

1. Choose Export… and name the map.
2. Keep Saved map, or choose Staged map to include your staged changes. Unstaged form edits are excluded.
3. Click Save map. The app validates and saves to the timestamped filename shown in the shared exports folder, without a separate Review step.

Use Choose file… or edit the path if you want another location. Apart from the dedicated exports folder, configuration, settings-backup, state and plugin directories remain protected. This is optional. Existing files still require Confirm overwrite. Changing the map name updates the suggested filename unless you have chosen a path yourself.

Commands and descriptions may contain private paths or secrets. Review the exported file before sharing it. Resolve stale overrides before exporting; the editor will not silently leave them out.

Import

Only import commands you trust. They are not run during preview, but can run when a shortcut is pressed after Apply.

1. Choose Import…. The app lists valid maps in the shared exports folder, showing their names, filenames and binding counts.
2. Optionally use Choose directory…, or edit the directory and press Refresh. Select a listed map to open its preview.
3. Use Merge to keep unrelated edits, or Replace to replace all editor customizations, including your current draft.
4. Review before/after values and commands. Resolve conflicting fields, select compatible local actions for unmatched entries, or skip them. Shared-shortcut warnings remain advisory.
5. Choose Stage import. Replace requires another confirmation; a partial replacement also requires accepting the skipped entries.
6. Review the main list, then Apply changes. Undo import restores the previous draft until another draft edit, reload, or Apply.

The browser checks file contents, not just filenames. Invalid, unreadable, oversized or special files are excluded with a count. Scans cover only the selected directory, not subdirectories. Very large directories return an error instead of an incomplete list. If a selected file has changed, refresh and review it again. File-format validation does not make its commands trustworthy.

Replace never rewrites your underlying Lua configuration. Removing an old customization restores its captured base binding. Importing an empty map in Replace mode therefore resets every editor customization, not every shortcut on your system.

On another machine, commands, paths, applications, layouts, and submaps may differ. Existing Lua actions stay on the receiving machine; they are not copied into the map. If a file or configuration changes during review, start a fresh preview. Cancel or timeout leaves the draft unchanged; if an export was already saving, check the destination before retrying.

Install

Requires a running Omarchy shell, Hyprland with Lua configuration, Python 3, Lua, and luac. The omarchy, omarchy-shell, hyprctl, and qs commands must be available. Installation runs as your normal user and does not install system packages.

Plugins run as unsandboxed code with your user permissions. Review the source before installing. This plugin also needs a one-time loader setup. Pressing Confirm in the first-open prompt authorizes it to back up and edit ~/.config/hypr/hyprland.lua, reload Hyprland, create its settings directory, and add an application-launcher entry. It checks that effective shortcuts are unchanged and attempts to restore the original configuration if setup fails. User-owned configuration symlinks within your home directory are preserved.

Catalog / Git installation

For a new installation:

omarchy plugin add https://github.com/Firstp1ck/omarchy-keybindings --enable

Review the installation confirmation. If you already used the marketplace's install command, skip this step and enable the plugin if needed with omarchy plugin enable firstpick.keybindings.

Open it:

omarchy-shell shell toggle firstpick.keybindings

The first-open prompt explains the configuration changes. Press Confirm to run setup, or Not now to leave your configuration untouched. No installer command is needed. While setup runs, the buttons are disabled; on success, the binding list opens automatically. Errors remain visible and retry requires another explicit confirmation.

Configured installations open normally without reinstalling, including installations with saved binding choices. Partial or conflicting loader blocks, existing launchers without a loader, or saved settings without a loader require recovery rather than an automatic reinstall. Installing or enabling the panel alone does not authorize setup; the prompt appears when you open it.

For terminal-based setup instead, review the installed install.py and run:

python3 -B "$HOME/.config/omarchy/plugins/firstpick.keybindings/install.py" setup

Run initial setup only once. If it fails, keep the reported backup and resolve the error before retrying. Do not delete saved settings to force setup.

Archive installation

Alternatively, download and extract the current source archive. Review the installer, then run from the extracted directory:

python3 install.py install

This copies the runtime and setup tools into your plugin directory, sets up the loader, and enables the panel. It does not create a Git checkout. Older tagged releases have their own installation instructions in the bundled README.

Existing copied installations

Keep your existing installation and use the copied-install update path below, including for version 0.2.1. The loader path and saved settings remain compatible. Do not run omarchy plugin add over an existing copy or delete saved settings to force setup; automatic conversion to a Git checkout is not supported.

Update

Save or discard drafts and close the editor before either update method.

Catalog / Git installation

Back up the installed plugin directory and your settings first. Review the proposed changes when prompted:

omarchy plugin update firstpick.keybindings && hyprctl reload
hyprctl configerrors

Continue only when there are no configuration errors. Restart the shell to clear cached panel code:

omarchy restart shell

Omarchy's Git updater validates the manifest, but it does not run this plugin's setup, compare effective shortcuts, or automatically undo a Hyprland reload failure. Do not rerun initial setup after each update. If a reload fails, keep the backup and restore the previous plugin files before reloading again. Catalog commands obtain current upstream code, not necessarily the marketplace's reviewed commit.

Copied installation

Download and extract the new source version, then run from that directory:

python3 update.py

This backs up the installed plugin, preserves saved bindings, verifies that shortcuts are unchanged, and restarts only Omarchy's shell to avoid stale QML caches. Hyprland and applications stay running. The custom updater refuses Git-managed installations; use the catalog update command for those.

Backups and recovery

• Binding-save backups: ~/.config/hypr/keybindings-editor/backups/
• Installation and loader-setup backups: ~/.local/state/omarchy-keybindings/install-backups/
• Copied-plugin update backups: ~/.local/state/omarchy-keybindings/update-backups/
• Before-detach backups: ~/.local/state/omarchy-keybindings/before-detach-*.lua
• Managed settings: ~/.config/hypr/keybindings-editor/overrides.lua

Failed Apply operations restore the previous managed settings and attempt another reload. Any failed rollback reload is reported in the panel. Do not edit the managed settings file by hand. Use Restore original for a binding, or Discard / reload for unsaved changes.

Remove

Detach the loader before removing plugin files. Save or discard drafts and close the editor, then run:

python3 "$HOME/.config/omarchy/plugins/firstpick.keybindings/install.py" uninstall

This disables the plugin, backs up and removes its loader blocks, reloads the underlying bindings, and removes its launcher entry. It keeps plugin files, saved settings, and backups for recovery. For older copied installations without an installed install.py, run python3 install.py uninstall from the original extracted project instead.

Only after detach succeeds, optionally remove the plugin directory:

omarchy plugin remove firstpick.keybindings

Omarchy deletes Git-managed plugin directories and backs up copied ones. Settings and loader backups live outside that directory and are retained. Removing the plugin without detaching does not clean up the loader or launcher; retained overrides stop applying after Hyprland next reloads. Do not remove files after a failed detach: restore or repair the loader first.

Limits

• The catalog covers bindings declared while your configuration loads. Later runtime-only bindings are not inventoried. Reload Hyprland to refresh the configuration catalog.
• Conflict checks compare key names, modifiers, trigger phases, submaps, and available device metadata. Physical keycodes versus symbol aliases and multiple keyboard layouts still need a manual check.
• Recording covers keyboard keys. Enter mouse bindings and AltGr/group-switch combinations manually. Unrecognized or shifted punctuation may use a physical keycode when available.
• Existing Lua actions are preserved, not editable as arbitrary Lua source. New actions use shell commands. Existing submaps and device-specific options are preserved; inherited bindings cannot be moved between submaps in this version.
• If source changes make an override stale, the editor warns and offers to remove it.
• If plugin code appears unchanged after an update, save pending edits before running omarchy restart shell. This restarts the bar and shell panels, not Hyprland or applications.

Support

Report bugs through GitHub Issues. Include your Omarchy, Hyprland, and Quickshell versions and steps to reproduce. Remove private commands and paths before sharing configuration or screenshots.

For implementation details, checks, and testing limits, see DEVELOPMENT.md.

License

MIT. Omarchy, Hyprland, and Quickshell are separate projects with their own licenses.