Proposal: managed Hyprland plugins through the existing plugin manager

[catlee]

I think this is worth exploring, but I’m not sure the current boundary is right yet.

Omarchy already has a way to install, enable, disable, update, and remove shell plugins. But changes to Hyprland still require editing ~/.config/hypr/ and managing imports by hand.

That applies to things like:

• keybindings
• monitors
• input settings
• window rules
• autostart

Could these become plugins too?

I’ve been working on this in a branch on my Omarchy fork. The current branch adds:

• a hyprland plugin kind;
• raw Lua entry points through entryPoints.hyprland;
• activation state in ~/.config/omarchy/hypr-plugins.json;
• a generated loader in ~/.local/state/omarchy/hypr/plugins.lua;
• dependency and priority ordering;
• enable, disable, update, and remove support;
• Hyprland reload and config-error checking.

The shape is partly inspired by lazy.nvim: a plugin manifest describes the entry point, dependencies, and priority, while the plugin itself remains code.

The first test plugin is omarchy-vim-bindings, a Vim-style h/j/k/l window-management keymap. It can be installed and removed through the plugin manager without adding an import to the user’s Hyprland config.

I’m mostly trying to figure out whether this is a good direction for Omarchy:

• Should Hyprland plugins use the existing plugin manager?
• Is raw Lua the right place to start?
• Should this eventually support describing bindings and window rules as data, instead of requiring every plugin to write Lua?
• Should Hyprland plugins appear alongside shell plugins in the same UI?
• Is a separate hypr-plugins.json file the right boundary?

The goal isn’t to add Vim bindings to Omarchy’s defaults. It’s to see whether Hyprland changes could become installable and manageable in the same way as other Omarchy customizations.

[catlee]

Quick demo showing how you can install this plugin via omarchy's plugin commands

screenrecording-2026-08-21_21-31-23.mp4

[brianblakely]

Would add toggles to this list so plugins like Peek have a supported path.

[catlee]

I’ve been trying this with a keyboard-tweaks plugin: Caps Lock/Escape remapping and key repeat are Hyprland settings, but the useful surface is a bar icon and a small settings popup.

That made me think a plugin should be able to have more than one kind. This one is hyprland + bar-widget: enabling it loads the input configuration and exposes its UI in the bar. The popup is owned by the widget, so it can anchor below its actual icon.

I also added a menu-entry integration. A plugin can declare an entry such as “Keyboard Tweaks” in its manifest, and the shell merges it into Setup only while the plugin is enabled. Its action summons the same widget popup.

That seems like a useful boundary: plugins can surface functionality in the bar when it needs quick access, or in the menu when it does not, without having to patch a user’s static menu configuration.

[catlee]

The proof of concept is now available at https://github.com/catlee/omarchy-keyboard-tweaks.

It is intentionally small: a Hyprland input component, a bar widget that owns the settings popup, and a manifest-provided Setup menu entry. Installing it through the plugin manager is enough to wire up all three.

[catlee]

I added a toggle plugin kind and pushed it to my hypr-plugins branch.

A toggle plugin declares toggles in its manifest. Each toggle has an id, label, icon, optional when/checked conditions, and an action. The shell adds enabled plugin toggles under Trigger > Toggle.

That gives plugins like Peek a direct path to the same on/off actions Omarchy already exposes, while the keyboard-tweaks proof of concept continues to use a normal Setup entry for its settings panel: https://github.com/catlee/omarchy-keyboard-tweaks

[catlee]

I think the smallest useful proposal is:

• extend the existing plugin manager to load hyprland entry points;
• keep the entry point as raw Lua for now;
• let a plugin optionally contribute a bar widget, menu entry, or toggle;
• keep plugin-owned state separate from the user’s static Hyprland and menu configuration.

I’m not proposing a declarative bindings or window-rules format yet. That can follow if raw Lua proves to be the wrong boundary.

The branch and the keyboard-tweaks plugin are intended as the reference implementation. Before turning this into a PR, does this seem like a direction Omarchy should support? If so, is there a narrower first slice you’d prefer?

[catlee]

Draft PR here: #8396