09b955dc75
* Give built-in plugins an honest on/off state Every built-in reported itself enabled no matter what. A bar widget said "enabled" while sitting nowhere near the bar, and disabling a built-in service silently did nothing, because enabled meant "listed in plugins[]" and a built-in never is. Nothing surfaced that, since the only caller listing plugins was the CLI. For a widget, on and off is its place in the bar, so listPlugins reports layout membership -- what enable/disable actually toggles. For everything else built in, loading by default is the right behaviour to keep, so switching one off is recorded the other way round, in disabledPlugins[]. shell.json still carries only the deviation from the defaults: the key is dropped the moment nothing is switched off, leaving a config that never disabled anything byte-identical. isEnabled still answers a separate question -- whether the component loads at all -- and deliberately does not follow a widget out of the bar. omarchy.menu is both a widget and the menu itself, so tying the two together would let taking its button off the bar lock the menu out of the shell, with no way back that isn't the CLI. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Manage plugins from Setup > Plugins Plugins were CLI-only. Setup > Plugins now offers Enable, Disable, Add, and Remove, each list living in the menu itself so picking a row acts on it. Enable and Disable cover the built-ins as well as anything installed -- the bar widgets you can put in the bar, the services and overlays you can switch off. Remove is limited to plugins the user installed, since a built-in has no checkout to delete, and stays hidden until there is one. Whole-bar replacements are left out; those are chosen under Style. Enabling a bar widget asks for a section first, because enabling alone drops it on the right and the only way to move it was a follow-up bar plugin move. The CLI asks the same question after its own add, so both paths place a widget the same way. Add and Remove run in a terminal: one needs a git URL and shows the trust warning before cloning, the other deletes a checkout and prints where it backed it up. Providers grew two hooks for this. placementFor turns a row into a submenu instead of an action, and volatile re-runs the enumeration when its submenu is entered -- picking from these lists is what changes them, and rows a provider no longer returns now drop out instead of lingering forever. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Trim the plugin menu after review Menu.qml carried its own shellQuote while already importing Util and calling Util.shellQuote a few lines up; two copies of the same escaping is one place for a future fix to miss. isDisabled walked the array by hand to compare values it writes itself, and dropDisabled was an eight-line helper with one caller. Two bugs came out of the same pass. A whole-bar replacement belongs under Style rather than these lists, but the exclusion sat in the shared row builder, so a third-party bar could be installed and never removed -- Remove would show an empty list under a guard that said something was there. The exclusion now sits on the two lists that mean it. Rows are keyed by id, and distinct plugin ids can slugify alike: acme.foo, acme_foo and acme-foo all give acme-foo. The merge keeps the first row per id, so the rest simply vanished from the list with nothing to say why. Row ids are now made distinct before merging. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Pick a plugin the way we pick a theme Setup > Plugins listed plugins as menu rows, which needed three providers, a placement submenu, a volatile-refresh hook and a row-swap in the merge. Only Font and Apps are built that way. Theme, Background, Unlock, Timezone and Keybindings all pipe a list into omarchy-menu-select instead, which is one action string and a small script -- so that is what these use now. The trade is search: a plugin name is no longer findable from the root prompt. Neither is a theme name or a timezone, and Enable Plugin still is, so the loss sits where the rest of the menu already puts it. Two pieces of the row machinery stay, because they are worth having for the lists that remain. A volatile provider re-runs when its submenu is entered, so a font installed since the shell started now shows up without restarting it, and rows a provider stops returning drop out. Row ids are still made distinct before merging: Fira Code and Fira-Code both slug to fira-code, and a repeated id was silently dropped. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Let a picked option carry an icon Moving the plugin lists onto omarchy-menu-select cost them their glyphs: the select mode has always hardcoded an empty icon, which is why Timezone and Keybindings have none either. An option may now lead with one, as "<glyph><TAB><label>". The menu shows the glyph, filters on the label, and hands the label back, so a caller never strips a glyph off its own selection and a list of plain strings behaves exactly as before. The plugin picker uses it for the puzzle glyph on each plugin and the align glyphs on the sections, which also regain the capitals they lost when the section names were passed through raw. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Switch bars by enabling one A bar option was kept out of Enable and Disable on the grounds that picking which bar to run belongs under Style -- but nothing under Style ever offered it, so an installed bar could be added and removed and never actually put to use. The menu was guarding a door to a room that was never built. Enabling one is the switch. setEnabled already assigns bar.id for a bar option, so a bar has always replaced the one before it; only the picker's filter stood in the way. Dropping it costs nothing else, because enabled for a bar option means active: the bar in use is the one row absent from Enable, every other installed bar is one pick away, and the built-in is just another entry, so going back to it is enabling Bar. Disable keeps the exclusion. That is the one verb a bar cannot answer -- there is no off, only a successor -- and offering it would have listed the built-in bar on a stock system, where turning it off deletes a bar.id that was never set and nothing happens. A bar carries the bar glyph rather than the puzzle one, so a row that replaces the whole bar does not read like one more widget to switch on, and enable now says "Now using X as the bar" instead of "Enabled X", which understated a whole-bar swap in both the enable and the freshly-added path. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Refuse a plugin that declares a kind it cannot load A kind is a promise to supply something to load, and the shell reads that something from a fixed key: entryPoints.bar to draw a bar, entryPoints.menu to open a menu. Nothing checked the promise. A manifest could claim kinds ["bar"] with no bar entry point, pass validation, install, and enable -- and then the bar would fall back to the built-in and the widget would be skipped, leaving a plugin that does nothing, explained only by a console.warn nobody reads. Our own plugins have been held to this table by plugins-test.sh all along. This holds third-party ones to the same table, at add and update time, where there is still someone to tell. A kind outside the table is left alone rather than guessed at, so a shell that learns a new kind does not need this list updated first. The cost is that a misspelled kind still installs quietly. omarchy-plugin-validate had no tests; it has some now. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Act on the plugin whose row was picked The picker showed a name and then looked that name up again across every plugin, filtered set or not, taking the first match. Two plugins can share a name: cloning one keeps the name it was cloned from, so the documented `omarchy plugin clone omarchy.clock local.clock` leaves two plugins called Clock. Enable listed the clone -- the built-in was already enabled, so only the clone was eligible -- and then enabled omarchy.clock, moving the built-in widget instead. Remove listed the clone and tried to delete a built-in that has no checkout to delete. A row now carries its id alongside its label, and the id is read back off the row that was picked instead of being derived from the name a second time. Where a name is not unique among the rows on offer, the label carries the id too, so two rows that would both say Clock can be told apart at all -- which they could not before, whichever one the pick resolved to. The verb prompt only ever sees the first two fields, so the menu shows what it always did. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Never ask a bar where to sit in the bar A manifest may declare both bar and bar-widget, and validation accepts it. The picker saw bar-widget, asked for a section, and passed it to enable. setEnabled takes bar as the dominant kind: it writes bar.id and returns, adding nothing to any layout, so the move that followed had no widget to find and failed -- after the bar had already been switched. A partial success with an error on the way out. Bar wins ahead of bar-widget now, in the picker and in the placement prompt `plugin add --enable` asks, so a bar is enabled without a placement it cannot use. The CLI refuses a placement on a bar outright, before the bar is switched rather than after, since `omarchy plugin enable <bar> --section left` could reach the same half-applied state without going through either. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Only replacement, no off * Add default placement for bar widgets * Simplify plugin menu actions * Document plugin placement behavior * Allow dropping widgets in empty bar space * Treat plugin dependencies as runtime invariants * Reject duplicate plugin ids on add --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
First-party plugins
These plugins ship with Omarchy and are discovered by the shell at startup.
They use the same manifest.json contract as third-party plugins; the
only difference is that the shell flags them with __isFirstParty: true.
First-party non-bar plugins are always enabled; omarchy.bar is the default
bar option and becomes inactive only while a third-party kind: "bar" plugin is
selected. Services and keep-loaded panels are mounted at startup; other panels,
overlays, and menus are loaded on demand.
User-installed plugins live alongside these conceptually but on disk under
~/.config/omarchy/plugins/<plugin-id>/ rather than in this directory.
| Plugin | id | kinds | entry point |
|---|---|---|---|
| Bar | omarchy.bar |
bar |
bar/Bar.qml |
| Image picker | omarchy.image-picker |
overlay |
image-picker/ImagePicker.qml |
| Emojis | omarchy.emojis |
overlay |
emojis/Emojis.qml |
| Clipboard mgr | omarchy.clipboard |
overlay |
clipboard/Clipboard.qml |
| Reminders | omarchy.reminders |
overlay |
reminders/ReminderFlow.qml |
| Omarchy menu | omarchy.menu |
menu, bar-widget |
menu/Menu.qml, menu/BarWidget.qml |
| Notifications | omarchy.notifications |
service |
notifications/Service.qml |
| Audio | omarchy.audio |
bar-widget |
panels/audio/Panel.qml |
| Bluetooth | omarchy.bluetooth |
bar-widget |
panels/bluetooth/Panel.qml |
| Clock | omarchy.clock |
bar-widget |
panels/clock/BarWidget.qml |
| Monitor | omarchy.monitor |
bar-widget |
panels/monitor/Panel.qml |
| Network | omarchy.network |
bar-widget |
panels/network/Panel.qml |
| Power | omarchy.power |
bar-widget |
panels/power/Panel.qml |
| Tailscale | omarchy.tailscale |
bar-widget |
panels/tailscale/Panel.qml |
| Model usage | omarchy.model-usage |
bar-widget |
model-usage/Panel.qml |
| Weather | omarchy.weather |
bar-widget |
panels/weather/BarWidget.qml |
| Media | omarchy.media |
service, bar-widget |
services/media/Service.qml, services/media/BarWidget.qml |
| Battery | omarchy.battery |
service |
services/battery/Service.qml |
| Idle | omarchy.idle |
service |
services/idle/Service.qml |
| Night light | omarchy.nightlight |
service |
services/nightlight/Service.qml |
| Lock screen | omarchy.lock |
service |
lock/Service.qml |
| OSD | omarchy.osd |
panel |
osd/Osd.qml |
| Polkit agent | omarchy.polkit |
service |
polkit/PolkitAgent.qml |
First-party bar-only widgets also carry manifests next to their QML files,
e.g. bar/widgets/Workspaces.manifest.json. Rich popup widgets live in their
own plugin directories, each with its own manifest.json.
Bar
The built-in status bar and default full-bar option. Layout lives in the
top-level bar: subtree of ~/.config/omarchy/shell.json (with the shell
providing config/omarchy/shell.json when
the user has no file). See bar/README.md for the widget catalogue
and customization schema.
Image picker
Fullscreen image-grid selector overlay. Used by omarchy-menu-images
(wallpaper picker) and omarchy-theme-switcher (theme picker) and any
other caller that wants to present a directory of images with previews.
Two ways to drive it:
- Shell-level summon:
omarchy-shell shell summon omarchy.image-picker '<jsonPayload>'. The payload can carryimageDirs,imageRows,selectedImage,selectionFile,doneFile,showLabels,filterable. Best for in-shell callers that already speak JSON. - Direct IPC target:
omarchy-shell image-selector open <imageDirs> <imageRowsB64> <selectedImage> <selectionFile> <doneFile> <showLabels> <filterable>. Positional args;imageRowsB64is base64-encoded so embedded newlines / tabs survive the bash argv handoff. This is whatomarchy-menu-imagesuses. Colors come from the central shell theme singleton; there is no per-call override surface.
The selection round-trip remains file-based: callers create a
selection_file and done_file (both mktemp), pass the paths, and
poll done_file for existence. The plugin writes the chosen path into
selection_file and touches done_file when it's done. cancel IPC
clears it without writing a selection.
The plugin has keepLoaded: true so the layer-shell window survives
between summons within a single shell session.
Lock screen
Session-lock surface using Quickshell's native WlSessionLock and two
separate PAM services: omarchy-lock-password for password auth and,
only when fingerprints are enrolled, omarchy-lock-fingerprint for
fingerprint auth. It mirrors the previous lock screen field dimensions,
colors, blurred wallpaper, placeholder, and Hyprland-driven corners.
Polkit agent
Theme-aware authentication dialog for privileged actions. It uses
Quickshell's native Quickshell.Services.Polkit.PolkitAgent backend and
runs inside the long-lived omarchy-shell process, replacing the old
polkit-gnome-authentication-agent-1 autostart.
Omarchy menu
Quickshell-powered Omarchy command menu.
The menu UI lives in menu/Menu.qml as a first-party menu plugin and is
summoned through the shell (omarchy-shell shell summon omarchy.menu ...),
so it shares the long-running omarchy-shell process instead of starting a
second Quickshell instance.
The menu definition lives outside the shell host code:
- defaults:
default/omarchy/omarchy-menu.jsonc - user extensions:
~/.config/omarchy/extensions/omarchy-menu.jsonc
The shell parses both JSONC files at startup (with watchChanges: true
so edits take effect without a restart), evaluates when: / checked:
bash expressions in a single batched subprocess, and executes the
selected action: string directly via Quickshell.execDetached. The
long-running shell process keeps the parsed menu in memory, so the
keybind → IPC → visible path costs ~30ms cold.
Coming soon
omarchy.theme-switcher— folds theme switching into the shell.