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

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, 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 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, 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 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 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 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 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 and 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 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 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 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 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 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 to determine eligibility and routing.

List all discovered plugins with their kinds:

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

Enable a specific plugin by its ID:

omarchy plugin enable omarchy.clock

Query the kind of a particular plugin:

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 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 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 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.

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