Omarchy Shell Root QML Entry Point Location and Architecture

The Omarchy desktop environment uses shell/shell.qml as its single entry point, loaded by the Quickshell runtime to bootstrap the entire QML-based UI.

The Omarchy desktop environment, maintained in the basecamp/omarchy repository under the quattro branch, implements its user interface using Qt Quick and the Quickshell framework. Understanding the Omarchy Shell Root QML entry point is essential for developers looking to customize the desktop or debug startup behavior. This file serves as the root component that instantiates all window management, plugin registries, and system services.

The Definitive Entry Point at shell/shell.qml

The Quickshell runtime specifically targets shell/shell.qml when initializing an Omarchy session. Located at the repository root in basecamp/omarchy, this file functions as the top-level QML component that constructs the primary ApplicationWindow and coordinates the desktop environment's core services.

According to the Omarchy source structure, shell/shell.qml performs several critical initialization tasks:

• Imports QtQuick and related Qt modules to establish the rendering context
• Creates the top-level window container that hosts all visual elements
• Instantiates service registries including the plugin manager and bar widget systems
• Establishes the object hierarchy where all subsequent UI components attach as children

Core Service Registries Loaded at Startup

Within shell/shell.qml, the root component immediately instantiates several singleton-like registries that manage the desktop's modular architecture:

• shell/services/PluginRegistry.qml: Registers and manages dynamic plugins that extend shell functionality
• shell/services/BarWidgetRegistry.qml: Controls the system bar widgets including workspace indicators and system tray elements

These registries load before any user-visible UI appears, ensuring all extensions are available when the bar and panels render.

How Quickshell Launches the Omarchy Shell

When an Omarchy session begins, the session manager (typically SDDM) executes the omarchy command, which internally invokes the Quickshell binary with the root QML file as an argument.

Launch Sequence Commands

From a terminal or display manager configuration, you can observe how the shell initializes:

# The standard launch command used by display managers

omarchy-launch

# Internally resolves to:

quickshell -f shell/shell.qml

This invocation instructs Quickshell to parse and execute shell/shell.qml, starting the event loop that drives the entire desktop environment.

Plugin Architecture and Child Components

All visible elements in Omarchy—panels, indicators, backgrounds, and workspace widgets—originate as children of the root component defined in shell/shell.qml. The repository organizes these extensions under the shell/plugins/ directory, where individual *.qml files implement specific features.

For example:

• shell/plugins/panel/Panel.qml renders the primary desktop panel
• shell/plugins/background/Background.qml handles wallpaper rendering
• Individual indicator plugins attach to the system bar via the registry system

Each plugin receives its configuration context from the root window established in shell/shell.qml.

Display Manager Integration and Session Handoff

Before the user shell loads, the SDDM login screen prepares the graphical session. Omarchy includes a dedicated display manager theme at default/sddm/omarchy/Main.qml, which provides the authentication interface. Upon successful login, control transfers from the SDDM process to the Quickshell runtime executing shell/shell.qml, ensuring a seamless transition from login screen to desktop.

Reloading the Shell During Development

Developers modifying QML components can reload the interface without terminating their session or logging out. The Omarchy framework exposes a DBus-based reload mechanism triggered via command line.

# Signal Quickshell to reload shell/shell.qml and all child components

omarchy-notification-send "reload"

This command causes the runtime to destroy and recreate the QML object tree defined in the root entry point, applying code changes instantly while preserving the underlying session.

Summary

• shell/shell.qml serves as the sole entry point for the Omarchy shell, loaded directly by the Quickshell runtime
• The root component instantiates service registries (PluginRegistry.qml, BarWidgetRegistry.qml) before rendering visible UI
• Launch occurs via omarchy-launch, which invokes quickshell -f shell/shell.qml
• All plugins and UI elements attach as children of the root component defined in the entry point
• Developers can hot-reload changes using omarchy-notification-send "reload" without session restart

Frequently Asked Questions

What is the main QML file for the Omarchy desktop?

The main entry point is shell/shell.qml in the basecamp/omarchy repository. This file contains the root QML component that Quickshell loads to initialize the entire desktop environment, including windows, panels, and service registries.

How does Quickshell load the Omarchy Shell Root QML?

Quickshell receives the explicit file path via the -f flag during invocation. The omarchy-launch wrapper script executes quickshell -f shell/shell.qml, causing the runtime to parse the root component and begin the QML execution context that drives the desktop.

Where are Omarchy plugins loaded from?

Individual plugins reside in shell/plugins/*/*.qml subdirectories. However, they are instantiated as children of the root component in shell/shell.qml through the PluginRegistry.qml service, which manages their lifecycle and registration with the main window.

How do I reload the Omarchy shell without logging out?

Execute omarchy-notification-send "reload" from a terminal. This sends a DBus signal that the Quickshell runtime interprets as a command to destroy and recreate the QML object tree defined in shell/shell.qml, applying code changes while keeping your session intact.

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