# What Is Quickshell in Omarchy?

> Discover Quickshell, Omarchy's core Wayland compositor and desktop toolkit. Learn how this single process powers your entire UI with dynamic JavaScript/QML plugins.

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

---

**Quickshell is the core Wayland compositor and desktop construction kit that powers Omarchy, running as a single long-lived process (`omarchy-shell`) that hosts all UI components—including the top bar, notifications, and lock screen—as dynamically loaded JavaScript/QML plugins.**

Omarchy relies on Quickshell to provide its graphical user interface without the bloat of traditional desktop environments. In the context of Basecamp's Omarchy project, Quickshell serves as both the window manager and the plugin host, enabling a modular, code-driven approach to desktop customization according to the source code in [`shell/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/README.md) and [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md).

## How Quickshell Powers the Omarchy Desktop

Unlike conventional Linux desktops that spawn separate executables for panels, menus, and notification daemons, Omarchy launches a single Quickshell instance named `omarchy-shell`. This process acts as a lightweight Wayland compositor that remains active for the entire session.

The architectural benefits of this design include:

- **Unified rendering** – All UI elements share the same graphics context and event loop, eliminating inter-process communication overhead between desktop components.
- **Session locking** – Quickshell provides native `WlSessionLock` support and a built-in Polkit agent (`Quickshell.Services.Polkit.PolkitAgent`), removing the need for external screen lockers or authentication daemons as noted in [`shell/plugins/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/README.md).
- **Resource efficiency** – By hosting the bar, menu, notifications, OSD pop-ups, and headless services (such as battery monitoring) within one process, Omarchy minimizes memory footprint and startup latency.

## The Quickshell Plugin Architecture

### Plugin Structure and Loading

Quickshell implements a plugin-centric architecture where desktop functionality is modular. Plugins are ordinary JavaScript/QML modules placed under the `shell/plugins/` directory. The Quickshell runtime automatically loads these modules during startup, allowing them to register UI elements, background services, and user actions.

According to [`manual/32-shell-plugins.md`](https://github.com/basecamp/omarchy/blob/main/manual/32-shell-plugins.md), plugins can expose:
- Visual widgets (labels, buttons, panels)
- Background services (monitoring, networking)
- Interactive menus and launchers
- System integration (notifications, lock screens)

### Configuration via JSONC

User customization occurs through JSONC files (JSON with comments), specifically `~/.config/omarchy/shell.json`. This configuration file dictates which plugins are active, their loading order, and arrangement parameters. The file layout and configuration system are documented in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md), which establishes the contract between Omarchy's configuration directory and the Quickshell runtime.

## Core Desktop Components as Plugins

Every visible element in the Omarchy desktop is implemented as a Quickshell plugin rather than a standalone application. The standard distribution includes plugins for:

- **Top bar** – System status, clock, and workspace indicators
- **Launcher menu** – Application search and execution interface
- **Notification server** – Wayland-native notification display
- **Lock screen** – Session security interface using `WlSessionLock`
- **OSD pop-ups** – Volume, brightness, and system feedback overlays
- **Polkit agent** – Privilege escalation dialogs
- **Headless services** – Battery monitoring and hardware event handling

This design is detailed in [`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md) and [`shell/plugins/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/README.md), which enumerate the available APIs and extension points.

## Working with Quickshell in Omarchy

### Starting the Desktop Shell

Under normal operation, Omarchy's initialization scripts launch the desktop environment by invoking the shell binary:

```bash
omarchy-shell

```

This command instantiates the single Quickshell process that hosts the entire desktop session. Developers should note that **additional standalone Quickshell instances must not be started**; all customization must occur through the plugin system as emphasized in [`agents/skills/shell-dev.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/shell-dev.md).

### Creating Your First Plugin

New plugins reside in the `shell/plugins/` hierarchy. A minimal plugin requires registration with the Quickshell runtime and implementation of lifecycle hooks. For example, creating [`shell/plugins/hello/hello.js`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/hello/hello.js):

```javascript
// shell/plugins/hello/hello.js – a minimal Quickshell plugin
Quickshell.registerPlugin({
  name: "hello",
  load() {
    Quickshell.notify("Hello from Quickshell!", { timeout: 3000 });
  },
});

```

### Registering Plugins in User Configuration

To activate the plugin, add its identifier to the user configuration file at `~/.config/omarchy/shell.json`:

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

```

The Quickshell runtime parses this JSONC file during initialization and loads the specified modules in order.

### Executing External Commands

Plugins can launch external applications without blocking the main shell process using the `execDetached` API. This method spawns independent processes suitable for launching terminals, browsers, or system utilities:

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

```

### Extending the Top Bar

Custom widgets integrate directly into the desktop chrome. The following example adds a clickable button to the top bar that launches a terminal:

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

```

## Development Guidelines and Constraints

The Omarchy project enforces strict architectural boundaries around Quickshell usage. As documented in [`agents/skills/shell-dev.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/shell-dev.md), developers must adhere to the plugin-only model:

- **No multiple instances** – Starting separate Quickshell processes outside of `omarchy-shell` is prohibited, as this would break the single-process model and cause resource conflicts.
- **Plugin isolation** – All custom logic, UI extensions, and background services must be implemented as plugins within `shell/plugins/` or user directories, not as external long-running scripts.
- **API stability** – Plugins should use the documented `Quickshell.*` APIs (such as `Quickshell.registerPlugin`, `Quickshell.notify`, and `Quickshell.addBarItem`) to ensure compatibility with future Omarchy updates.

## Summary

- Quickshell functions as Omarchy's Wayland compositor and sole desktop process (`omarchy-shell`), replacing the traditional multi-daemon desktop architecture.
- All UI components—including the bar, notifications, menus, and lock screen—are implemented as JavaScript/QML plugins loaded from `shell/plugins/`.
- Configuration occurs through JSONC files (`~/.config/omarchy/shell.json`) that specify active plugins and layout parameters.
- The system provides APIs such as `Quickshell.execDetached` for non-blocking process execution and `Quickshell.addBarItem` for UI extension.
- Development requires adherence to a strict single-process model, prohibiting the launch of additional Quickshell instances outside the managed session.

## Frequently Asked Questions

### What programming languages are used to write Quickshell plugins?

Quickshell plugins are authored in **JavaScript** and **QML** (Qt Modeling Language). These languages provide declarative UI construction and imperative logic, allowing developers to create everything from simple notification scripts to complex interactive widgets. The runtime exposes native APIs through the global `Quickshell` object, as demonstrated in [`shell/plugins/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/README.md).

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

Traditional environments like GNOME or KDE spawn separate executables for panels (`gnome-panel`, `plasmashell`), notification daemons (`dunst`, `mako`), and compositors (`mutter`, `kwin`). Quickshell inverts this model by hosting all components within a single `omarchy-shell` process using a plugin architecture. This eliminates IPC overhead, reduces memory usage, and enables tighter integration between desktop elements.

### Can I run Quickshell outside of Omarchy?

While Quickshell is technically a standalone project, Omarchy treats it as an embedded dependency. The [`agents/skills/shell-dev.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/shell-dev.md) file explicitly warns against starting additional Quickshell instances outside of the managed `omarchy-shell` process. Attempting to run Quickshell independently on an Omarchy system may cause display server conflicts and configuration inconsistencies.

### Where are Quickshell plugins stored in the Omarchy repository?

Official plugins reside in the `shell/plugins/` directory, with individual subdirectories containing JavaScript logic and QML interface definitions. User-created plugins can be added to `~/.config/omarchy/shell/plugins/` or registered via the global configuration. The repository layout is documented in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md), which maps the relationship between the Quickshell runtime and the Omarchy configuration hierarchy.