omarchy/default/agents/skills/omarchy/plugins.md

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

Plugin UI Safety

Plugins run inside Omarchy's long-lived, unsandboxed shell. Treat text from network responses, files, IPC, settings, environment variables, and command output as untrusted.

• QML Text defaults to Text.AutoText. Do not bind untrusted data to an AutoText sink: markup-shaped input such as <img src="https://example.invalid/tracker"> can be interpreted as rich text and load a resource.
• For display text owned by the plugin, set textFormat: Text.PlainText. Prefer a local PlainText component when the plugin has multiple text elements.

Text {
  textFormat: Text.PlainText
  text: modelData.name
}

• When passing dynamic text to an Omarchy-owned component whose internal Text format the plugin cannot set, neutralize markup in the plugin first with a helper of its own, and add a regression test; Omarchy ships no such helper. Never edit the packaged component to add a plain-text option: that belongs in a pull request to Omarchy.
• Bound and validate downloaded data before displaying or saving it: limit response and collection sizes, string lengths, identifiers, and timestamps.
• Keep network access explicit. Use fixed HTTPS sources, timeouts, response-size limits, and validation. For periodic background refreshes, disclose the behavior and let users enable or disable it. Never execute downloaded content or interpolate untrusted values into shell commands.
• Add regression coverage for markup-shaped input and every shared tooltip or notification sink that receives dynamic text.

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.