# What is Quickshell in the Context of Omarchy: Desktop Construction Kit Explained

> Discover Quickshell, the core desktop construction kit powering Omarchy. Learn how this Wayland compositor hosts UI components as modular JavaScript/QML plugins.

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

---

**Quickshell is the core desktop construction kit that powers Omarchy's graphical environment, acting as a single long-lived Wayland compositor process that hosts all UI components as modular JavaScript/QML plugins.**

Omarchy is a Linux desktop environment developed by Basecamp that leverages Quickshell as its foundational framework. Understanding what Quickshell is in the context of Omarchy reveals a tightly integrated, single-process architecture that replaces traditional multi-component desktop setups. This article explores how Quickshell functions as both the Wayland compositor and plugin host, based on the source code in the `basecamp/omarchy` repository.

## The Quickshell Architecture in Omarchy

### Single-Process Desktop Model

Omarchy launches a single long-running process called `omarchy-shell` that serves as the entire graphical session. Unlike traditional desktops that spawn separate applications for the panel, notifications, and menus, Quickshell hosts every visual element within this one instance. This design eliminates inter-process communication overhead and ensures instant UI responsiveness. According to the documentation in [`shell/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/README.md), this single-process approach is fundamental to Omarchy's lightweight resource profile.

### Plugin-Based UI System

Every visible interface element in Omarchy—from the **top-bar** and **launcher menu** to **notifications**, **on-screen-display (OSD) pop-ups**, and the **lock-screen**—is implemented as a Quickshell plugin. These plugins are ordinary JavaScript/QML modules placed under the `shell/plugins/` directory. The Quickshell runtime loads these modules automatically and provides them with APIs to register UI elements, execute commands, and respond to system events. As documented in [`manual/32-shell-plugins.md`](https://github.com/basecamp/omarchy/blob/main/manual/32-shell-plugins.md), this modular architecture allows users to enable, disable, or rearrange desktop components without modifying core system files.

### Wayland Native Integration

Quickshell provides native Wayland compositing capabilities, removing the need for external compositors like Hyprland or Sway. The framework implements **WlSessionLock** for secure screen locking and includes a built-in Polkit agent (`Quickshell.Services.Polkit.PolkitAgent`) for authentication dialogs. Additional headless services, such as battery monitoring and idle management, run as background plugins within the same process. The [`shell/plugins/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/README.md) file details how these components interact with the underlying Wayland protocol.

## Configuration and Extensibility

### JSONC Configuration Files

Users control Quickshell's behavior through JSONC (JSON with Comments) configuration files stored in `~/.config/omarchy/shell.json`. This configuration specifies which plugins are active, their arrangement on screen, and theme-specific settings. The repository's [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) describes how this configuration layer integrates with the broader Omarchy file structure, ensuring that user customizations persist across updates.

### Developer Constraints and Best Practices

The Omarchy project enforces strict architectural boundaries for developers. According to [`agents/skills/shell-dev.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/shell-dev.md), developers must **never** launch additional standalone Quickshell instances. All customization logic belongs in plugins loaded by the primary `omarchy-shell` process. This constraint maintains system stability and prevents configuration conflicts that could arise from multiple compositor instances competing for Wayland resources.

## Practical Implementation Examples

The following examples demonstrate how to interact with Quickshell in the Omarchy environment.

Starting the Omarchy shell (normally invoked by system initialization):

```bash
omarchy-shell

```

Creating a minimal plugin at [`shell/plugins/hello/hello.js`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/hello/hello.js):

```javascript
// Register a plugin that shows a notification on load
Quickshell.registerPlugin({
  name: "hello",
  load() {
    Quickshell.notify("Hello from Quickshell!", { timeout: 3000 });
  },
});

```

Activating the plugin via user configuration in `~/.config/omarchy/shell.json`:

```json
{
  "plugins": ["hello"]
}

```

Executing external commands without blocking the shell process:

```javascript
Quickshell.execDetached("xdg-open", ["https://example.com"]);

```

Adding a custom bar item programmatically:

```javascript
Quickshell.registerPlugin({
  name: "myBar",
  load() {
    Quickshell.addBarItem({
      widget: Quickshell.Label({ text: "🖥️ MyBar" }),
      click: () => Quickshell.execDetached("alacritty")
    });
  },
});

```

## Summary

- Quickshell serves as Omarchy's **desktop construction kit**, providing both the Wayland compositor and plugin runtime in a single process.
- All UI components—including the bar, menus, notifications, and lock screen—are implemented as **plugins** under `shell/plugins/` rather than standalone applications.
- Configuration occurs through **JSONC files** in `~/.config/omarchy/`, allowing users to customize their desktop without touching source code.
- The architecture requires **exactly one Quickshell instance** per session; developers must extend functionality through plugins rather than spawning new processes.
- Quickshell offers native **Wayland integration** with built-in session locking and Polkit authentication, eliminating dependencies on external compositors.

## Frequently Asked Questions

### How does Quickshell differ from traditional desktop environments?

Traditional desktops like GNOME or KDE spawn separate processes for panels, notification daemons, and window managers. Quickshell consolidates all these functions into a single `omarchy-shell` process that acts as both compositor and plugin host. This eliminates IPC overhead and creates a unified theming model where all components share the same memory space and rendering context.

### Can I run multiple Quickshell instances on Omarchy?

No. The Omarchy architecture explicitly forbids running additional Quickshell instances beyond the primary `omarchy-shell` process. Starting secondary instances would create conflicts over Wayland socket ownership and display resources. All customization must be implemented as plugins loaded by the existing process, as documented in [`agents/skills/shell-dev.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/shell-dev.md).

### Where are Quickshell plugins stored in Omarchy?

Built-in plugins reside in the repository's `shell/plugins/` directory, while user-developed plugins can be placed in `~/.config/omarchy/plugins/` or equivalent user configuration paths. Each plugin is a self-contained JavaScript/QML module that the Quickshell runtime discovers and loads based on the active configuration in [`shell.json`](https://github.com/basecamp/omarchy/blob/main/shell.json).

### How do I configure which Quickshell plugins load at startup?

Edit the JSONC configuration file located at `~/.config/omarchy/shell.json` and modify the `"plugins"` array to include the names of desired plugins. Changes take effect when the Quickshell process restarts. The [`manual/32-shell-plugins.md`](https://github.com/basecamp/omarchy/blob/main/manual/32-shell-plugins.md) file provides the complete schema for plugin configuration, including parameters for positioning and theming.