What Is Quickshell in Omarchy?

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 and 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.
• 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, 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, 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 and 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:

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.

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:

// 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:

{
  "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:

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:

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

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 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, which maps the relationship between the Quickshell runtime and the Omarchy configuration hierarchy.

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