plugins

Omarchy Shell: Bar, Plugins, and Idle

Read this before changing the status bar, notifications, shell plugins, widgets, or idle/lock behavior.

The bar, notification daemon, settings panel, and assorted overlays all run inside a single long-running Quickshell process (`omarchy-shell`).

~/.config/omarchy/shell.json             # User overrides: bar, plugins, idle
~/.config/omarchy/plugins/<plugin-id>/   # User-owned shell plugins
$OMARCHY_PATH/config/omarchy/shell.json  # Canonical defaults

The shell hot-reloads `shell.json` on save — no restart needed for layout changes. `idle.screensaver` and `idle.lock` are seconds since user idle began.

**Commands:** `omarchy restart shell`, `omarchy refresh shell`

Bar Layout

Use the `omarchy bar` group to move and manage widgets:

omarchy bar move omarchy.clock --section right

For layout edits beyond what the commands cover, edit the bar configuration in `~/.config/omarchy/shell.json`; it hot-reloads on save.

Customizing Built-In Plugins and Widgets

To customize a built-in bar widget, never edit `$OMARCHY_PATH/shell/plugins/`. Clone it into the user plugin directory instead:

omarchy plugin clone omarchy.workspaces
# Edit ~/.config/omarchy/plugins/<username>.workspaces/; saved changes reload automatically.

Cloning switches the bar to the cloned copy (e.g. `<username>.workspaces`), which is yours to edit and survives updates.

Saving a file anywhere under `~/.config/omarchy/plugins/` reloads plugin code automatically. If a change somehow fails to apply, force a reload with `omarchy-shell shell rescanPlugins`.

Idle and Lock

Set `idle.screensaver` and `idle.lock` in `~/.config/omarchy/shell.json`, in seconds since user idle began. Example: "lock after ten minutes" means setting `idle.lock` to `600`.