David Heinemeier HanssonandClaude Opus 5
e2d655d265
Clicking the clock reveals a month grid with ISO week numbers, a year progress meter, and month stepping. Right click walks the common label formats and writes the chosen one back to shell.json, so the bar shows what the config stores. The week start toggles from the grid's "W" heading and persists as weekStartDay, defaulting to the locale's own first day. Rich popup widgets live in their own plugin directories, so the clock moves out of bar/widgets/ into panels/clock/. The id is unchanged, so existing layouts and centerAnchor keep working. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
117 lines
6.9 KiB
Markdown
117 lines
6.9 KiB
Markdown
# 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/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` |
|
|
| 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`](../../config/omarchy/shell.json) when
|
|
the user has no file). See [`bar/README.md`](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 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.
|