arthur-os/shell/plugins/README.md

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
Launcher	omarchy.launcher	overlay	launcher/Launcher.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, bar-widget	notifications/Service.qml, notifications/BarWidget.qml
Audio	omarchy.audio	bar-widget	panels/audio/Panel.qml
Bluetooth	omarchy.bluetooth	bar-widget	panels/bluetooth/Panel.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/Widget.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
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/Clock.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.

Launcher

Quickshell-powered launcher. It uses Quickshell's native DesktopEntries model for discovery/activation and renders inside the long-running shell with the legacy launcher card dimensions, colors, row spacing, icon sizing, and keyboard behavior. Summoned directly over shell IPC by the SUPER + SPACE binding and the Omarchy menu Apps row.

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 carry imageDirs, 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; imageRowsB64 is base64-encoded so embedded newlines / tabs survive the bash argv handoff. This is what omarchy-menu-images uses. 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.