What Is Quickshell in Omarchy? Understanding the Desktop Construction Kit

Quickshell is the core Wayland compositor and plugin host that powers Omarchy’s graphical environment, running as a single long-lived process that loads modular UI components as JavaScript/QML plugins.

Quickshell serves as the desktop construction kit for the Omarchy operating system, providing the foundational framework for all graphical user interface elements. Unlike traditional desktop environments that spawn separate applications for panels and menus, Omarchy utilizes a unified Quickshell instance—omarchy-shell—that acts as both compositor and plugin runtime. This architecture delivers tight system integration and consistent theming across the entire user experience.

The Single-Process Architecture

Omarchy runs one persistent Quickshell process named omarchy-shell that lives for the entire user session. This design eliminates the overhead of managing multiple standalone applications for different UI components, reducing memory footprint and communication latency. The process initializes the Wayland display server, loads the user configuration, and mounts all UI plugins into a single runtime environment.

According to the repository documentation in [shell/README.md](https://github.com/basecamp/omarchy/blob/quattro/shell/README.md), this single-process model is fundamental to Omarchy’s performance characteristics. When the system initializes the graphical session, it executes omarchy-shell once, and this instance remains active until logout, hosting every visible interface element.

Plugin Architecture and UI Components

All user-facing elements in Omarchy are implemented as Quickshell plugins located under the shell/plugins/ directory. These plugins are ordinary JavaScript/QML modules that the Quickshell runtime loads dynamically based on user configuration. The system ships with a comprehensive set of built-in plugins that provide essential desktop functionality.

Core Plugin Categories

The Omarchy distribution includes plugins for every major UI surface:

• Top-bar and panel drop-downs – Status indicators and system trays
• Launcher menu – Application finder and command palette
• Notifications – Native notification server and history
• OSD pop-ups – Volume, brightness, and system feedback overlays
• Lock-screen – Session locking interface utilizing WlSessionLock
• Headless services – Background monitors such as battery status and idle management

As detailed in [manual/32-shell-plugins.md](https://github.com/basecamp/omarchy/blob/quattro/manual/32-shell-plugins.md), each plugin operates within the shared Quickshell process space, allowing direct access to system state and rapid UI updates without inter-process communication overhead.

Configuration and File Layout

Users control which plugins load and how they behave through JSONC configuration files, typically stored at ~/.config/omarchy/shell.json. This configuration format supports comments and dictates plugin activation order, positioning, and behavioral parameters.

The file layout documentation in [docs/file-layout.md](https://github.com/basecamp/omarchy/blob/quattro/docs/file-layout.md) describes how Quickshell integrates with Omarchy’s broader configuration system. The runtime monitors these configuration files for changes, enabling hot-reloading of UI components without restarting the session.

Wayland Integration and System Services

Quickshell provides native Wayland compositing capabilities, eliminating the need for external window managers or standalone compositors. It directly implements critical system services that other desktop environments often delegate to separate daemons.

Native System Implementation

The Quickshell runtime handles:

• Wayland compositing – Direct management of window surfaces and input events
• Session locking – Secure screen locking via the WlSessionLock protocol
• Authorization agents – PolicyKit integration through Quickshell.Services.Polkit.PolkitAgent
• Headless execution – Background command execution without UI blocking

These capabilities are documented in [shell/plugins/README.md](https://github.com/basecamp/omarchy/blob/quattro/shell/plugins/README.md), which outlines the API surface available to plugin developers.

Development Best Practices

Developers extending Omarchy’s desktop must adhere to specific architectural constraints. The Quickshell environment is designed to host all logic within its plugin system rather than through external processes.

According to [agents/skills/shell-dev.md](https://github.com/basecamp/omarchy/blob/quattro/agents/skills/shell-dev.md), developers must never spawn additional standalone Quickshell instances. All custom functionality—including background services, UI widgets, and system integrations—must be implemented as plugins loaded by the central omarchy-shell process. This constraint preserves the single-process architecture and ensures consistent state management across the desktop environment.

Practical Code Examples

Starting the Omarchy Shell

Normally initiated by the system initialization scripts, the shell binary runs as a singleton:

omarchy-shell

Creating a Minimal Plugin

Define a new plugin by creating a JavaScript file in shell/plugins/hello/hello.js:

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

Activating the Plugin

Add the plugin identifier to your user configuration:

{
  "plugins": ["hello"]
}

Executing External Commands

Plugins can launch external applications without blocking the UI thread:

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

Adding Custom Bar Items

Extend the top panel with custom widgets:

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

Summary

• Quickshell is the unified runtime for Omarchy’s graphical environment, combining Wayland compositor and plugin host into the single omarchy-shell process.
• All UI elements are plugins loaded from shell/plugins/, including the bar, menu, notifications, and lock screen.
• Configuration uses JSONC files stored in ~/.config/omarchy/, enabling hot-reloading of components.
• Wayland integration is native, supplying session locking and Polkit authentication without external daemons.
• Development requires strict adherence to the plugin model—additional Quickshell instances are prohibited.

Frequently Asked Questions

What is the difference between Quickshell and omarchy-shell?

Quickshell refers to the underlying framework and API that provides the desktop construction kit, while omarchy-shell is the specific binary and process name used by Omarchy to launch its Quickshell instance. In the Omarchy context, these terms are closely related, but omarchy-shell specifically denotes the configured runtime that loads Omarchy’s plugin set.

How do I add a custom plugin to Omarchy’s Quickshell?

Create a JavaScript file in the shell/plugins/ directory, implement the Quickshell.registerPlugin() interface, and add the plugin name to your ~/.config/omarchy/shell.json configuration. The Quickshell runtime automatically discovers and loads valid plugins on startup or configuration reload.

Can I run multiple Quickshell instances on Omarchy?

No, Omarchy’s architecture depends on a single omarchy-shell process. Running additional instances would break the single-process model and cause conflicts over Wayland display ownership. All custom functionality must be implemented as plugins within the existing instance, as enforced by the development guidelines in the shell-dev skill documentation.

What technologies are used for Quickshell plugin development?

Plugins are written in JavaScript and QML (Qt Meta Language), utilizing the Quickshell API for UI components and system integration. The runtime executes these scripts within the main process, providing direct access to Wayland primitives, system notifications, and execution utilities like Quickshell.execDetached().

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