# Quickshell Shell Plugin Kinds: The Complete Guide to Omarchy UI Architecture

> Explore the ten Quickshell plugin kinds for Omarchy UI architecture: bar, panel, overlay, service, background, menu, notification, osd, and agent. Learn how UI elements integrate with the shell.

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

---

**The Quickshell-based Omarchy desktop supports ten distinct plugin kinds—`bar`, `bar-widget`, `panel`, `overlay`, `service`, `background`, `menu`, `notification`, `osd`, and `agent`—that define how UI elements and background services integrate with the shell at runtime.**

The Omarchy desktop environment from `basecamp/omarchy` treats nearly every interface element as a dynamically discovered plugin managed by the Quickshell. Each plugin declares its architectural role through the `kind` or `kinds` field in its [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json), enabling the shell to correctly route user interactions, layout decisions, and background processing.

## Understanding Quickshell Plugin Architecture

The Quickshell shell discovers and loads plugins at runtime by reading their [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) files. The manifest includes a **`kind`** property (or **`kinds`** for multi-role plugins) that maps the plugin to a specific architectural category. This system allows the shell to enforce constraints—such as allowing only one active `bar` plugin while permitting multiple `bar-widget` plugins—without hardcoding component logic.

According to the Omarchy source code, the plugin registry validates these kinds at startup. The manifest schema is documented in [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md), while individual plugin manifests reside in `shell/plugins/<category>/<name>/manifest.json`.

## The 10 Supported Quickshell Plugin Kinds

### Bar Plugins

The **`bar`** kind represents the top-level status bar that houses widgets. Only one bar plugin can be active at a time, making this a singleton role within the shell.

**Example:** [`shell/plugins/bar/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/bar/manifest.json) declares `"kind": "bar"` to register the built-in Omarchy bar.

### Bar-Widget Plugins

**`bar-widget`** plugins are small UI components that render inside the bar, such as clocks, network indicators, and system trays. Multiple bar-widgets can coexist within a single bar instance.

**Example:** The clock widget at [`shell/plugins/panels/clock/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/panels/clock/manifest.json) uses `"kind": "bar-widget"`, as does the network indicator.

### Panel Plugins

The **`panel`** kind defines drop-down interfaces that appear when users activate bar widgets. These expand from the bar to display detailed information or controls.

**Example:** [`shell/plugins/panels/weather/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/panels/weather/manifest.json) declares `"kind": "panel"` for the weather drop-down, while the Dropbox and Tailscale plugins use the same kind for their respective panels.

### Overlay Plugins

**`overlay`** plugins render full-screen or modal UI that sits above the desktop session. These capture input and block interaction with underlying windows until dismissed.

**Example:** The lock screen at [`shell/plugins/lock/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/lock/manifest.json) uses `"kind": "overlay"`, as do the emoji picker and clipboard manager.

### Service Plugins

The **`service`** kind represents headless background processes that maintain state and expose data to other plugins. These have no UI components but provide essential system functionality.

**Example:** [`shell/plugins/services/battery/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/services/battery/manifest.json) and [`shell/plugins/services/nightlight/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/services/nightlight/manifest.json) both declare `"kind": "service"` to manage power and display settings respectively.

### Background Plugins

**`background`** plugins control desktop wallpaper rendering and background-related UI effects. These interact with the compositor to set the visual foundation of the workspace.

**Example:** [`shell/plugins/background/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/background/manifest.json) uses `"kind": "background"` to manage the desktop background.

### Menu Plugins

The **`menu`** kind implements the application launcher or "hamburger" menu interface. This is typically a singleton role responsible for the main program grid.

**Example:** [`shell/plugins/menu/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/menu/manifest.json) declares `"kind": "menu"` for the Omarchy application menu.

### Notification Plugins

**`notification`** plugins handle system alerts, banners, and Do-Not-Disturb state management. These integrate with the desktop's notification daemon to display incoming alerts.

**Example:** [`shell/plugins/notifications/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/notifications/manifest.json) uses `"kind": "notification"` to provide the notification system.

### OSD Plugins

The **`osd`** (On-Screen Display) kind renders transient visual feedback for volume changes, brightness adjustments, and other hardware controls.

**Example:** [`shell/plugins/osd/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/osd/manifest.json) declares `"kind": "osd"` for volume and brightness indicators.

### Agent Plugins

**`agent`** plugins are long-running background coordinators that manage complex asynchronous tasks such as backups, synchronization, or maintenance scripts.

**Example:** [`shell/plugins/agents/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/agents/manifest.json) uses `"kind": "agent"` for the backup agent system.

## How Plugin Kinds Work in Practice

The `omarchy plugin` CLI interacts with the Quickshell registry to manage plugins based on their declared kinds. The shell reads each plugin's [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) to determine eligibility and routing.

List all discovered plugins with their kinds:

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

```

Enable a specific plugin by its ID:

```bash
omarchy plugin enable omarchy.clock

```

Query the kind of a particular plugin:

```bash
PLUGIN_ID=omarchy.tailscale
omarchy plugin list --json | jq -r --arg id "$PLUGIN_ID" '.[] | select(.id==$id) | .kinds'

```

The `--json` flag returns machine-readable output where the `kinds` field contains an array of declared kinds. Multi-kind plugins—those declaring both `"panel"` and `"bar-widget"` in the same manifest—appear with multiple entries in this array.

## Summary

- The Quickshell shell supports **ten plugin kinds**: `bar`, `bar-widget`, `panel`, `overlay`, `service`, `background`, `menu`, `notification`, `osd`, and `agent`.
- Each kind maps to a specific architectural role, from UI containers (`bar`) to headless processes (`service`, `agent`).
- Plugins declare kinds in [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) files located at `shell/plugins/<category>/<name>/manifest.json`.
- The `omarchy plugin` CLI uses these declarations to validate, enable, and route plugin functionality at runtime.
- Multi-kind plugins can fulfill multiple roles simultaneously by declaring an array of kinds in their manifest.

## Frequently Asked Questions

### What is the difference between bar and bar-widget plugins?

**`bar`** plugins define the container itself—the top-level panel that spans the screen—and only one can be active at a time. **`bar-widget`** plugins are the individual components that render inside that container, such as clocks or network indicators, and multiple widgets can coexist within a single bar.

### Can a single plugin declare multiple kinds?

Yes. The [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) schema supports a `kinds` array that allows one plugin to fulfill multiple roles. For example, a plugin might declare both `"bar-widget"` and `"panel"` to provide a compact bar indicator that expands into a detailed drop-down when clicked.

### How do I check what kinds a plugin supports?

Use the `omarchy plugin list --json` command and filter for the `kinds` field. For a specific plugin ID, pipe the output through `jq` to select the relevant entry, as shown in the code examples above. This inspects the plugin's [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) directly from the shell's registry.

### Which plugin kind should I use for system background tasks?

Use the **`service`** kind for stateful background processes that expose data to UI components, such as battery monitoring or media control. For long-running coordination tasks like backups or synchronization, use the **`agent`** kind instead.