# What Is the Quickshell Desktop Shell in Omarchy?

> Explore the Quickshell desktop shell in Omarchy, a single-process QML runtime. Discover how it loads UI components as plugins for a flexible and efficient user experience.

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

---

**The Quickshell desktop shell in Omarchy is a single-process QML runtime that hosts all UI components—from the status bar to panels and menus—as dynamically loadable plugins, controlled via IPC and configured through a central JSON file.**

The **Quickshell desktop shell** serves as the foundation of Omarchy's desktop environment, developed in the `basecamp/omarchy` repository. Unlike traditional desktop shells that spawn discrete processes for different UI elements, Omarchy runs everything inside one long-running Quickshell instance launched by Hyprland. This unified architecture minimizes memory overhead while enabling rapid inter-process communication between desktop components.

## Core Architecture of the Quickshell Desktop Shell

### Single-Process Runtime Model

The Omarchy shell operates as a solitary long-running process where all UI components coexist. Because the **Quickshell desktop shell** hosts everything inside one instance, shared services and singletons exist only once according to the source code, eliminating the memory bloat associated with spawning separate `quickshell -p …` processes for individual panels or widgets.

### Entry Point and Boot Sequence

The shell initializes through `shell/shell.qml`, which instantiates the root `ShellRoot` object. Hyprland triggers this automatically at session start via the `omarchy-shell` script, though manual invocation is possible:

```bash
quickshell -p $OMARCHY_PATH/shell

```

## Plugin System and Service Layer

### Plugin Manifests and Types

Every UI element loads as a QML bundle requiring a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) file that declares the plugin's **kind** and entry points. Valid kinds include `bar-widget`, `panel`, `overlay`, `menu`, `service`, and `bar`. The shell loads these on demand via IPC calls such as `summon`, `hide`, and `toggle`, rather than maintaining all components in memory simultaneously.

### Registry Services

Two critical QML services manage the plugin lifecycle:

- **`shell/services/PluginRegistry.qml`** discovers plugins, validates their manifests, and tracks enabled states via [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json).
- **`shell/services/BarWidgetRegistry.qml`** aggregates all bar widgets, both first-party and third-party, into a unified collection.

## IPC Interface and Configuration

### The shell.json Configuration File

All persistent state resides in `~/.config/omarchy/shell.json`, which stores the bar layout, idle timers, and enabled plugin list. The runtime reads this file at startup, and changes trigger a reload via the command `omarchy-shell shell reloadConfig`.

A minimal configuration defines the bar position and widget layout:

```json
{
  "version": 1,
  "bar": {
    "id": "omarchy.bar",
    "position": "top",
    "layout": {
      "left": [{ "id": "omarchy.menu" }],
      "center": [{ "id": "omarchy.clock", "format": "HH:mm" }],
      "right": [{ "id": "omarchy.audio" }]
    }
  },
  "plugins": []
}

```

### Available IPC Commands

The shell exposes a single `shell` IPC target and supports commands defined in the IPC contract:

```bash

# Verify shell responsiveness

omarchy-shell shell ping

# Toggle a specific menu

omarchy-shell shell toggle omarchy.menu '{"menu":"root"}'

# List all discovered plugins

omarchy-shell shell listPlugins

# Rescan for new or updated plugins

omarchy-shell shell rescanPlugins

```

Additional supported commands include `summon <id>`, `hide <id>`, `call <id> <method>`, and `setPluginEnabled`.

## Extending the Shell with Third-Party Plugins

Developers extend the **Quickshell desktop shell** by cloning Git repositories into `~/.config/omarchy/plugins/<id>/`. The shell monitors this directory and can hot-reload plugins without restarting the session using `omarchy-shell shell rescanPlugins`. This model allows third-party contributions to integrate seamlessly with built-in components like the bar or background switcher.

## Summary

- The **Quickshell desktop shell** is a single-process QML runtime that consolidates all Omarchy UI elements into one instance.
- Components load as plugins with [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) files defining kinds such as `bar-widget`, `panel`, or `menu`.
- Core services in `shell/services/PluginRegistry.qml` and `BarWidgetRegistry.qml` manage plugin discovery and widget aggregation.
- Configuration persists in `~/.config/omarchy/shell.json`, read at startup and reloadable via IPC.
- The shell exposes IPC commands including `ping`, `summon`, `hide`, `toggle`, and `rescanPlugins` through the `bin/omarchy-shell` wrapper.
- Third-party plugins install to `~/.config/omarchy/plugins/<id>/` and support hot-reloading.

## Frequently Asked Questions

### What is Quickshell in the context of Omarchy?

In Omarchy, **Quickshell** is the underlying QML framework that powers the desktop shell. It provides the runtime environment that loads and executes the `shell/shell.qml` entry point, enabling a plugin-based architecture where all UI components run within a single process rather than as separate applications.

### How do you enable or disable plugins in Omarchy's Quickshell?

Plugin states are managed through the `setPluginEnabled` IPC command or by manually editing the `plugins` array in `~/.config/omarchy/shell.json`. After modifying the configuration, run `omarchy-shell shell reloadConfig` to apply changes without restarting the session.

### Where is the Quickshell configuration stored in Omarchy?

All persistent configuration for the **Quickshell desktop shell** lives in `~/.config/omarchy/shell.json`. This file controls the bar layout, enabled plugins, idle timers, and other runtime parameters that the shell reads during initialization.

### How does the IPC system work in Omarchi's Quickshell?

The shell exposes a unified IPC target named `shell` that accepts commands through the `bin/omarchy-shell` helper script. Commands such as `ping`, `summon <id>`, `hide <id>`, and `rescanPlugins` allow external processes and user scripts to control panel visibility, reload configurations, and manage plugin states dynamically.