Plugins
What plugins are
The Omarchy desktop runs as a single long-lived Quickshell process, and nearly everything on screen is a plugin inside it: the bar, the panels that drop from it, the emoji picker, the clipboard manager, the menu, the lock screen, and the background services. First-party plugins ship with Omarchy; anything you add lives in ~/.config/omarchy/plugins/.
A plugin is a directory with a manifest.json and some QML. Its id is namespaced — the omarchy. prefix is reserved for first-party plugins.
When a theme wants a plugin
The line is straightforward. A theme changes colour. A plugin changes behaviour or structure. If what you want is not expressible in colors.toml or shell.toml, you want a plugin.
| What you want | Where it belongs |
|---|---|
| Different colours anywhere in the desktop | Theme — colors.toml |
| Different bar height, corner radius, border widths, font scale, spacing | Theme — shell.toml or a shell.<section>.toml override |
| A different lock-screen or notification treatment | Theme — shell.lock.toml, shell.notifications.toml |
| A new item in the bar, or a bar laid out differently | Plugin |
| A new panel, overlay or background service | Plugin |
| Behaviour that reacts to system state | Plugin |
Plenty of visual ambition is reachable without a plugin: shell.toml covers bar sizing, control states in every interaction state, per-side border widths, gradient borders, corner radius and the typographic scale. Try that first — it installs with your theme and needs no trust from the person installing it.
Where to find and publish plugins
Omarchy has a community plugin marketplace at plugins.omarchy.org . omarchy.org/plugins redirects there. It has a browsable catalogue, a guide to developing a plugin, and instructions for publishing one; the marketplace itself is open source at omacom/omarchy-plugin-marketplace .
If your theme pairs well with a specific plugin, link it from your README rather than bundling it. A theme cannot install a plugin, and it should not try to.
omarchy plugin list # what is installed, and what is enabled
omarchy plugin add <git-url> --enable # install from a repository
omarchy plugin enable omarchy.tailscale
omarchy plugin disable omarchy.weather
omarchy plugin clone omarchy.clock # copy a built-in and modify it
omarchy plugin update # fast-forward every git-managed plugin
omarchy plugin remove acme.weatherPlugins are code, themes are not
This distinction is the reason the two are separate. An installed theme is filtered down to colour before it is staged. A plugin is not: it runs as unsandboxed code inside your long-lived shell process, for as long as your session lasts, with everything your user account can reach.
Omarchy says so plainly and asks you to confirm before adding one. It clones files, validates the manifest and flips a setting — it never runs an install hook and never asks for sudo — but that only covers installation. Read a plugin before you enable it, and link plugins from your theme with the same care you would recommend any other program.