# Understanding the Different Plugin Kinds in Omarchy

> Explore the six plugin kinds in Omarchy: bar widget, panel, overlay, menu, service, and bar. Learn how Omarchy loads, displays, and manages components within its Quickshell process.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: deep-dive
- Published: 2026-08-23

---

**Omarchy defines six distinct plugin kinds—`bar-widget`, `panel`, `overlay`, `menu`, `service`, and `bar`—that determine how components are loaded, displayed, and managed within the long‑living Quickshell process.**

The Omarchy desktop environment from `basecamp/omarchy` is architected around a modular plugin system where every visible component is a plugin. Each plugin declares its capabilities through a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) file, using the `kinds` field to tell the shell exactly where the component can appear in the UI and how it should be instantiated.

## The Six Plugin Kinds Defined

The `kinds` array in [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) supports the following values, as documented in [`manual/32-shell-plugins.md`](https://github.com/basecamp/omarchy/blob/main/manual/32-shell-plugins.md) and enforced by the shell’s validation logic:

### `bar-widget`

A component that the active bar can place into a section, such as a clock, network indicator, or media controller. When declaring this kind, the manifest may include a `barWidget` block that configures the **display name**, **category**, **default section**, and whether **multiple instances** are allowed.

### `panel`

A persistent or summoned floating window that overlays the desktop but does not cover the entire screen. Weather widgets, system monitors, or notification centers typically implement this kind.

### `overlay`

A fullscreen surface that covers the whole screen, blocking interaction with underlying windows. Common examples include the emoji picker and clipboard manager.

### `menu`

A summoned menu surface that appears on user interaction. The Omarchy menu itself is implemented as a plugin of this kind.

### `service`

A headless singleton with no UI, typically running background tasks such as battery monitoring, network polling, or media session tracking. Services start automatically when enabled and run continuously until the shell exits.

### `bar`

A full‑bar replacement that swaps out the built‑in bar entirely. Only one bar plugin can be active at a time, as it assumes responsibility for the entire top or bottom screen edge.

## How Plugin Kinds Drive System Behavior

The `kinds` declaration is not merely descriptive; it dictates core shell behavior across discovery, lifecycle management, and extension.

### Discovery and Loading

At startup, the `omarchy-shell` process scans two locations for valid plugins:

1. **`$OMARCHY_PATH/shell/plugins/`** for first‑party plugins bundled with Omarchy
2. **`~/.config/omarchy/plugins/`** for third‑party user installations

The shell validates each discovered [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) and maps the declared `kinds` to specific **entry points** defined in the `entryPoints` object. For example, a plugin declaring both `service` and `bar-widget` must provide corresponding QML files:

```json
{
  "schemaVersion": 1,
  "id": "acme.media",
  "name": "Media Controller",
  "kinds": ["service", "bar-widget"],
  "entryPoints": {
    "service": "Service.qml",
    "barWidget": "Widget.qml"
  },
  "barWidget": {
    "displayName": "Media",
    "category": "media",
    "allowMultiple": false
  }
}

```

### Enable and Disable Logic

Enabling a plugin persists its ID to `~/.config/omarchy/shell.json` in a location appropriate to its kind:

- **Bar widgets** are added to the bar layout configuration
- **Non‑widget first‑party plugins** are tracked in `enabledPlugins[]` or removed from `disabledPlugins[]`

Disabling reverses these mutations, ensuring the shell does not load entry points for inactive plugins on the next start.

### Cloning and Extending

When cloning a built‑in plugin using `omarchy plugin clone`, the new copy inherits the original’s `kinds` array. This allows developers to modify UI components or business logic without breaking the shell’s expectations about where the plugin can appear.

## Validating Plugin Kinds

The `bin/omarchy-plugin-validate` CLI tool ensures that every declared kind has a matching entry point in [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json). This validation prevents runtime errors by catching mismatches between the `kinds` array and the `entryPoints` object before the shell attempts to load the plugin.

The test suite in [`test/shell.d/plugins-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/plugins-test.sh) further enforces these contracts, confirming that:

- Plugins with `bar-widget` kind correctly expose `barWidget` metadata
- Multi‑kind plugins load all declared entry points
- Invalid kind declarations are rejected during the validation phase

## Practical Examples

List discovered plugins with their kinds:

```bash
omarchy plugin list --json | jq '.[] | {id, kinds}'

```

Enable a specific bar‑widget:

```bash
omarchy plugin enable myclock.bar-widget

```

Add a third‑party plugin providing both a panel and a service:

```bash
omarchy plugin add https://github.com/acme/omarchy-weather.git --enable

```

## Summary

- Omarchy recognizes **six plugin kinds**: `bar-widget`, `panel`, `overlay`, `menu`, `service`, and `bar`.
- The `kinds` array in [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) determines which **entry points** the shell loads and where UI components appear.
- **Bar widgets** support additional configuration via the `barWidget` block for display metadata and instance limits.
- Plugins are discovered in `$OMARCHY_PATH/shell/plugins/` and `~/.config/omarchy/plugins/`, with enablement state stored in `~/.config/omarchy/shell.json`.
- Validation is handled by `bin/omarchy-plugin-validate` and verified by [`test/shell.d/plugins-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/plugins-test.sh).

## Frequently Asked Questions

### Can a single plugin declare multiple kinds?

Yes. A plugin can declare multiple kinds simultaneously in its [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json). For example, the media plugin is both a `service` (for background playback monitoring) and a `bar-widget` (for the control interface). Each kind requires a corresponding entry point in the `entryPoints` object.

### Where are plugin kinds documented for developers?

The canonical reference is [`shell/plugins/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/README.md), which lists each supported kind and its required entry points. User‑facing documentation covering kind behavior and configuration options is maintained in [`manual/32-shell-plugins.md`](https://github.com/basecamp/omarchy/blob/main/manual/32-shell-plugins.md).

### How does Omarchy handle conflicts between bar plugins?

Only one plugin of kind `bar` can be active at a time because it replaces the entire built‑in bar. Attempting to enable a second bar plugin typically disables the first, with the shell logging a warning about the replacement. Bar widgets (`bar-widget`), however, can coexist in unlimited numbers within the active bar.

### What happens if a plugin declares a kind but omits the entry point?

The `bin/omarchy-plugin-validate` command will reject the manifest with a validation error. The shell requires that every string in the `kinds` array has a matching key in `entryPoints` (e.g., `service` maps to a `service` key, `bar-widget` maps to `barWidget`). This ensures the shell can resolve the QML file path during initialization.