Quickshell in Omarchy: the shell, plugins, QML and failure diagnosis

Quickshell is a toolkit/runtime for building desktop interfaces with QML. Omarchy Shell is the interface Omarchy builds on it. They are related but not interchangeable: installing Quickshell alone does not reconstruct Omarchy’s menus, plugin settings or services. This article explains the pinned Omarchy Shell integration; an older Waybar installation needs its own documentation.

The upstream introduction teaches QML windows and reactive components. Omarchy’s shell documentation explains its hosting and IPC model. Use the interaction layer for the full category list.

How a click reaches a system capability

user clicks a bar widget
  → Omarchy Shell opens a panel/plugin
  → plugin reads or requests a backend capability
  → backend changes/reports state
  → reactive UI displays the new state

Hyprland presents the shell's surfaces;
Quickshell hosts them, rather than managing every backend itself.

Desktop control	Relevant backend boundary	What UI visibility does not prove
Network panel	NetworkManager	That an adapter is connected or working
Audio panel	PipeWire/WirePlumber integration	That the intended speaker/microphone route is selected
Battery widget	Power/device information	That suspend or battery health is solved
Workspace widget	Hyprland state/actions	That every workspace has the intended monitor assignment
Notification interface	Notification service and app requests	That an application emitted a notification

If a network panel opens but the connection fails, investigate networking as well as UI. If windows and keyboard work but all shell controls vanish, inspect the shell first. See Hyprland for compositor responsibilities.

One host, several plugin kinds

In the pinned implementation, one long-running Quickshell instance hosts bars, widgets, panels, overlays, menus and services. A bar widget is part of a bar; a full-bar plugin replaces the bar; a service can have no visible surface. Only one full bar is active, and the built-in bar is the documented fallback if a selected replacement cannot load.

This explains why “restart the bar” can restart more than a single strip of pixels: multiple controls and services share the host. Some kept-loaded services retain their instance across code reload; their code changes need a deliberate shell restart. Do not restart the shell while relying on an active lock operation.

Choose the correct customization layer

Layer in the pinned layout	Purpose	Common mistake
~/.config/omarchy/shell.json	Layout, selected plugins and personal settings	Replacing the whole file with a tiny sample
~/.config/omarchy/shell.toml	Personal appearance overrides	Expecting a theme switch to remove a hardcoded local size
Active theme’s shell.toml	Theme appearance tokens	Editing generated output as if it were permanent source
~/.config/omarchy/plugins/<id>/	Personal/installed plugin source	Confusing a clone with the original bundled source
Packaged shell/ tree	Omarchy’s host and built-in implementation	Editing shipped code for a small widget preference

For widget order and clock format, use the bar guide and supported controls first. QML source work is appropriate when behavior cannot be expressed through a setting, not a prerequisite for moving a clock.

Inspect health without launching a duplicate desktop

From the user’s active desktop session, run:

omarchy-shell shell ping
omarchy plugin list
pgrep -af quickshell

The first is the pinned host’s IPC health check. A successful response establishes that the host answers, not that every plugin and backend works. The list distinguishes active/installed plugins. Process names alone can include more than one instance or command lines, so they are not a complete diagnosis.

The wrapper fails if the shell is not running; its quiet -q mode is best-effort and unsuitable when you need to see an error. Generic qs/quickshell launch commands can select a different configuration; do not start another copy as a health check. For CLI/log facilities, inspect the installed qs --help and match the upstream documentation version rather than assuming a universal log path.

Observation	Next investigation
IPC does not answer, windows still work	Host startup/process/configuration and the session context
IPC answers, one widget is absent	Placement, plugin enabled state and plugin load error
Panel opens but operation fails	Its backend and requested device/action
Appearance wrong after theme switch	Personal TOML overrides and theme application
Two bars overlap	More than one host/configuration or another bar started
Code edit seems ignored	Editing the selected clone? Kept-loaded service? Reload lifecycle?

After identifying and restoring a broken personal setting/plugin, a deliberate omarchy-restart-shell can be appropriate in this pinned version. Save the diagnostic message first. Do not restart Hyprland or reset all configuration just to repair one panel.

Learn QML in a separate small window

Upstream tutorials commonly begin with a panel that reserves desktop space. For a first learning experiment, an independent floating window makes the boundary clearer. Check qs --help for --path/-p support and match your runtime to the v0.3.0 FloatingWindow reference.

Create a fresh ~/quickshell-guide directory only if it does not already contain your work. Put this original learning example in its shell.qml; do not replace Omarchy’s shell files:

import Quickshell
import QtQuick

FloatingWindow {
    visible: true
    implicitWidth: 360
    implicitHeight: 140
    color: "#1f1f28"

    Text {
        anchors.centerIn: parent
        text: "My separate QML window"
        color: "#dcd7ba"
        font.pixelSize: 20
    }
}

Launch this explicitly selected file from an ordinary terminal:

qs -p "$HOME/quickshell-guide/shell.qml"

Expected result: one independent learning window, without replacing the Omarchy bar. Change only text, save and observe the upstream live-reload behavior. If a type/property is unknown, keep the exact error and check the runtime’s matching documentation; do not modify the production host to force the example to load. Use Ctrl + C in this launcher terminal to stop the practice process, or close its window. Do not terminate every Quickshell process, since that can stop Omarchy Shell too.

The example is source-reviewed, not validated in your session. Its purpose is to connect QML object, property, child item and file selection before introducing plugins and backend actions.

Move from learning to a plugin deliberately

Omarchy supports cloning built-in plugins to personal IDs and preserving documented integration identities. Use its clone workflow to learn from the actual source, keep a saved original and test one UI-only change before adding processes or service actions. The bar guide gives a smaller configuration task when source work is unnecessary.

Plugins run as user-level code in the shared host, not a sandbox. The pinned plugin-add workflow starts third-party additions disabled for review, and update workflows expose changes. API facades constrain supported integration, but do not make unknown QML incapable of file/process access. Review code and dependencies before enabling a plugin; avoid bypassing normal prompts just to make installation shorter.

For recovery, restore the edited personal file or disable the specific offending plugin, then inspect health again. Removing an active built-in clone is documented to return to its built-in source; keep a copy of your edits before using removal. A useful report identifies Omarchy/Quickshell versions, plugin ID, last change, IPC result and exact load error. That information separates toolkit issues, host integration and backend failures instead of calling every missing icon a Quickshell bug.