Omarchy Plugin Kinds Explained: A Complete Guide to Plugin Types in the Omarchy Desktop

Omarchy plugin kinds are categorical declarations in each plugin's manifest.json that define how the shell loads, renders, and manages the plugin—ranging from UI components like bar and panel to background service and agents plugins.

The Omarchy desktop environment is built entirely around a plugin-first architecture. Almost every visual element and background process you interact with is implemented as a plugin that declares one of several predefined kinds. Understanding these plugin kinds is essential for customizing your desktop, developing new extensions, or troubleshooting plugin behavior.

What Are Omarchy Plugin Kinds?

In the Omarchy codebase, a plugin kind is a type discriminator defined in manifest.json that tells the shell:

• Where to render the plugin (top bar, overlay, background service)
• How many instances can exist (only one bar, multiple bar-widget entries)
• When to activate it (at startup, on demand, or via user interaction)

The shell discovers plugins at startup, validates their declared kind, and loads them according to role-specific rules.

Complete List of Omarchy Plugin Kinds

Based on the Omarchy source code in omacom/omarchy, the following plugin kinds are currently defined:

Kind	Purpose	Runtime Behavior
bar	Top-level container for desktop widgets	Singleton—only one bar plugin active at any time
bar-widget	Individual widgets rendered inside the bar	Multiple allowed; positioned via bar layout configuration
panel	Dropdown panels triggered by bar widgets	Rendered as modal dropdowns (e.g., Wi-Fi QR, Tailscale)
overlay	Full-screen or modal UI layers	Temporarily covers entire desktop (emoji picker, clipboard, image picker)
service	Background state providers	Long-running, no UI; exposes state to other plugins
notification	System notification UI	Displays transient toast notifications
menu	Central Omarchy configuration menu	Accessed via "Setup > Plugins" interface
lock	Session lock screen	Full-screen overlay when session is locked
image-picker	Image selection interface	Specialized overlay for screenshot/file selection workflows
agents	Headless job runners	Execute background tasks and expose data to panels

Plugin Kind Examples from Source Files

Each plugin kind is declared in its respective manifest.json. Here are the key file paths that define these kinds in the Omarchy repository:

# Bar plugin (singleton container)

shell/plugins/bar/manifest.json

# Bar widgets (multiple instances allowed)

shell/plugins/panels/audio/manifest.json
shell/plugins/panels/network/manifest.json

# Dropdown panels

shell/plugins/panels/wifiqr/manifest.json

# Overlay plugins

shell/plugins/emojis/manifest.json
shell/plugins/image-picker/manifest.json

# Background services

shell/plugins/services/nightlight/manifest.json
shell/plugins/services/battery/manifest.json

# System UI plugins

shell/plugins/notifications/manifest.json
shell/plugins/menu/manifest.json
shell/plugins/lock/manifest.json

# Agent plugins

shell/plugins/agents/manifest.json

How Plugin Kinds Affect Loading Behavior

The shell's plugin discovery logic—as documented in shell/README.md—handles each kind differently:

1. bar plugins: The shell loads exactly one active bar plugin. Switching bars requires disabling the current one and enabling another.

2. bar-widget and non-bar plugins: These are enabled by default unless explicitly listed in disabledPlugins[] in your configuration.

3. service plugins: Start automatically at shell initialization and run continuously, exposing reactive state to UI plugins.

4. overlay, panel, menu, lock, image-picker: Loaded on-demand when triggered by user interaction or system events.

5. agents: Execute scheduled or event-driven background jobs, feeding data into panels or services.

Working with Plugin Kinds: CLI Examples

# List all discovered plugins with their kinds

omarchy plugin list --json | jq '.[] | {id: .id, kind: .kind}'

# Enable a bar-widget plugin

omarchy plugin enable omarchy.audio

# Disable a service plugin

omarchy plugin disable omarchy.nightlight

# Check which bar plugin is currently active

omarchy plugin list --json | jq 'select(.kind == "bar" and .enabled)'

# View all enabled service plugins

omarchy plugin list --json | jq 'select(.kind == "service" and .enabled)'

Where Plugin Kinds Are Documented

The Omarchy codebase contains authoritative documentation for plugin kinds in two primary locations:

• shell/README.md (plugin discovery section): Describes how the shell validates kinds, handles the singleton bar constraint, and manages the disabledPlugins[] array.

• manual/32-shell-plugins.md: User-facing guide explaining that "almost everything you see on screen is a plugin" and detailing how different plugin families work together.

Summary

• Omarchy plugin kinds are declared in manifest.json and determine shell behavior.
• Ten kinds exist: bar, bar-widget, panel, overlay, service, notification, menu, lock, image-picker, and agents.
• Only one bar plugin can be active; other kinds support multiple instances or singletons based on role.
• Services and agents run invisibly; overlays, panels, and menus provide on-demand UI.
• Kind-specific loading rules are enforced in shell/README.md and the plugin discovery implementation.

Frequently Asked Questions

What happens if I try to enable two bar plugins at once?

The shell enforces a singleton constraint on bar plugins. According to the plugin discovery logic in shell/README.md, enabling a second bar plugin automatically disables the currently active one. Only one bar can render at any time.

Can I create custom plugin kinds?

The current Omarchy implementation recognizes a fixed set of kinds defined in the shell's plugin loader. While you can extend existing kinds with custom functionality, new kind types require modifications to the shell's core discovery and rendering code in the shell/plugins directory.

How do I disable a plugin kind globally?

Non-bar plugins are enabled by default, but you can disable specific plugins by adding their IDs to the disabledPlugins[] array in your Omarchy configuration. The bar plugin is handled separately—you explicitly enable one bar at a time rather than disabling bars globally.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}