# Omarchy Plugin Kinds Explained: A Complete Guide to Plugin Types in the Omarchy Desktop > Understand Omarchy plugin kinds. Learn how manifest.json defines UI, service, and agent plugins for loading, rendering, and management in this comprehensive guide. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: deep-dive - Published: 2026-09-01 --- **Omarchy plugin kinds are categorical declarations in each plugin's [`manifest.json`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/manifest.json). Here are the key file paths that define these kinds in the Omarchy repository: ```bash # 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`](https://github.com/omacom/omarchy/blob/main/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 ```bash # 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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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.