How Omarchy Launches and Restarts Its Desktop Shell: Complete Technical Guide

The Omarchy desktop shell uses a bin/omarchy-shell wrapper script to launch Quickshell with shell.qml, and supports both full restarts via SIGTERM + re-execution and lightweight config reloads through IPC commands.

The Omarchy desktop environment is built on Quickshell, a QML-based compositor. Understanding how the shell starts and recovers is essential for troubleshooting crashes, developing plugins, or automating deployments. This guide examines the actual implementation in the omacom/omarchy repository.

How Omarchy Shell Launch Works

Entry Point: bin/omarchy-shell

All shell lifecycle operations flow through the helper script at bin/omarchy-shell. This script performs three critical functions before handing control to Quickshell:

1. Lockfile verification — Checks $XDG_RUNTIME_DIR/omarchy-shell.lock to prevent duplicate instances
2. Environment setup — Exports OMARCHY_PATH and updates $PATH to include bin/
3. Process execution — Spawns Quickshell with the main QML entry point

The core exec call follows this pattern:

exec "$(command -v quickshell)" \
    --qml "$(realpath "$OMARCHY_PATH/shell/shell.qml")"

This replaces the shell process with Quickshell, making omarchy-shell a true launcher rather than a persistent parent.

QML Initialization in shell.qml

The shell/shell.qml file serves as the top-level QML component. It:

• Builds the desktop UI (panels, widgets, wallpapers)
• Registers service objects for IPC communication
• Establishes the OmarchyShell component with bidirectional message channels

After spawning, the launcher writes the Quickshell PID to the lockfile, enabling later control commands to locate the running instance.

Omarchy Shell Restart Mechanisms

The repository implements two distinct restart strategies depending on whether you need a full process recycle or a configuration refresh.

Method 1: Full Process Restart

omarchy-shell restart (or omarchy-shell -r) performs a hard restart:

• Reads PID from $XDG_RUNTIME_DIR/omarchy-shell.lock
• Sends SIGTERM or SIGINT to the Quickshell process
• Immediately re-executes the launch sequence described above

This method guarantees a clean state—useful after plugin installations, Quickshell updates, or crash recovery. The implementation resides entirely within bin/omarchy-shell.

Method 2: Lightweight Config Reload

omarchy-shell reloadConfig uses IPC for faster turnaround:

• Sends message omarchy-shell shell reloadConfig to the running instance
• The QML component catches this via its IPC channel
• Either re-loads the QML tree in-place or triggers Qt.quit() followed by controlled restart

This approach preserves window states and connected clients where possible. The IPC infrastructure leverages utilities in shell/Commons/Util.qml.

Restart Test Coverage

Automated verification exists at [test/shell.d/restart-shell-test.sh](https://github.com/omacom/omarchy/blob/quattro/test/shell.d/restart-shell-test.sh). This test validates that:

• Lockfiles are properly cleaned on exit
• The restart command successfully spawns a new process
• IPC channels remain functional across reloads

Practical Commands for Shell Control

# Start shell (typically invoked by session manager, not manually)

omarchy-shell

# Full restart after configuration changes or crashes

omarchy-shell restart

# Quick reload without dropping windows or connections

omarchy-shell reloadConfig

# Verify shell responsiveness

omarchy-shell shell ping

Supporting Configuration

File	Role in Launch/Restart
bin/omarchy-shell	Primary launcher with sub-commands for restart and IPC
bin/omarchy-shell-config	Pre-launch configuration copier; seeds ~/.config/omarchy with defaults
shell/shell.qml	Quickshell entry point; handles UI construction and IPC message dispatch
shell/Commons/Util.qml	Shared utilities for environment queries and IPC operations

Summary

• Launch — omarchy-shell prepares environment, validates lockfile, and execs Quickshell with shell.qml
• Full restart — omarchy-shell restart terminates and respawns the entire process tree
• Config reload — omarchy-shell reloadConfig uses IPC to refresh QML without full restart
• Lockfile management — PID tracking at $XDG_RUNTIME_DIR/omarchy-shell.lock enables reliable process control
• Test coverage — test/shell.d/restart-shell-test.sh automates restart validation

Frequently Asked Questions

What happens if I run omarchy-shell while the desktop is already running?

The launcher detects the existing lockfile and exits with a message rather than spawning a second instance. Use omarchy-shell restart or omarchy-shell reloadConfig to affect the running shell.

Does Omarchy preserve window state across restarts?

Full restarts (omarchy-shell restart) terminate Quickshell completely—window state depends on your compositor's session restoration. Config reloads (reloadConfig) attempt to preserve state by re-loading QML in-place where Quickshell supports it.

Where does Omarchy store its lockfile and runtime state?

The lockfile is written to $XDG_RUNTIME_DIR/omarchy-shell.lock. User configuration is managed in ~/.config/omarchy, with defaults seeded by omarchy-shell-config on first launch.

How can I debug why the shell fails to start?

Check lockfile presence manually, verify OMARCHY_PATH points to valid installation files, and ensure quickshell binary is in $PATH. The omarchy-shell script performs these validations and reports specific failures before attempting execution.

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