# Omarchy Shell Root QML Entry Point Location and Architecture > Discover the Omarchy shell root QML entry point. Learn about shell.qml, the Quickshell runtime, and the QML UI architecture in this technical guide. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: architecture - Published: 2026-08-24 --- **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: ```bash # 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. ```bash # 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.