How to Launch or Restart the Omarchy Shell: Complete Guide

Use omarchy-launch-shell to start the Omarchy shell and omarchy-restart-shell to safely stop and restart it while preserving your Hyprland session.

The Omarchy shell serves as the long-running core of the Omarchy declarative desktop environment, hosting first-party plugins and providing IPC capabilities through Quickshell. Whether you are configuring a fresh Hyprland session or applying changes to QML configuration files, understanding how to properly launch or restart the Omarchy shell ensures your desktop remains responsive and synchronized with your configuration.

Starting the Shell with omarchy-launch-shell

The primary entry point for initializing the shell is the helper script omarchy-launch-shell, located at bin/omarchy-launch-shell in the repository. This script orchestrates the startup sequence by spawning the omarchy-shell daemon and registering it with the Hyprland window manager via Quickshell.

When executed, omarchy-launch-shell performs three critical operations:

• Spawns omarchy-shell as a background daemon
• Registers the new shell instance with Hyprland using the command hyprctl dispatch 'hl.dsp.exec_cmd("omarchy-launch-shell")'
• Writes the process ID to $HOME/.local/state/omarchy/shell.pid for lifecycle management

To launch the shell manually from a terminal:

# Start the shell in the background

$ omarchy-launch-shell &

Typically, this command is invoked automatically during login via an autostart script rather than manually.

Restarting Safely with omarchy-restart-shell

When modifying QML files in shell/shell.qml or recovering from an unresponsive desktop, use omarchy-restart-shell to gracefully cycle the shell process. This script, located at bin/omarchy-restart-shell, ensures a clean shutdown before starting a fresh instance, preventing zombie processes and socket conflicts at $XDG_RUNTIME_DIR/omarchy-shell.sock.

The restart workflow follows this sequence:

1. Locates the existing PID via $HOME/.local/state/omarchy/shell.pid
2. Sends SIGTERM to the running process and waits for exit
3. Clears the lock file at $HOME/.local/state/omarchy/restart-shell-called to prevent stale locks
4. Invokes omarchy-launch-shell while preserving the $OMARCHY_PATH environment variable

Execute the restart from any terminal:

# Safely restart to apply QML changes or recover from hangs

$ omarchy-restart-shell

Runtime IPC and Verification

Once active, the shell exposes an IPC interface through the omarchy-shell binary. This client communicates via a Unix socket at $XDG_RUNTIME_DIR/omarchy-shell.sock and routes commands to appropriate QML plugins through the Quickshell IPC bridge.

Verify that the shell is responsive:

$ omarchy-shell shell ping

Refresh specific widgets without a full restart:

$ omarchy-shell -q omarchy.clock refresh

Key Files and State Management

The shell maintains runtime state in $HOME/.local/state/omarchy/:

Component	Source Path	Purpose
Launch script	bin/omarchy-launch-shell	Spawns daemon and registers with Hyprland
Restart script	bin/omarchy-restart-shell	Manages graceful shutdown using lock files
IPC binary	bin/omarchy-shell	Unix socket client for runtime commands
UI definition	shell/shell.qml	Core QML loaded by Quickshell
PID file	$HOME/.local/state/omarchy/shell.pid	Tracks active shell process

Summary

• omarchy-launch-shell initiates the Omarchy shell process, registers it with Hyprland via hyprctl dispatch, and writes the PID to $HOME/.local/state/omarchy/shell.pid
• omarchy-restart-shell safely terminates the existing shell using the PID file, clears the lock at $HOME/.local/state/omarchy/restart-shell-called, and starts a fresh instance
• The omarchy-shell binary provides runtime IPC via Unix socket at $XDG_RUNTIME_DIR/omarchy-shell.sock
• Always use omarchy-restart-shell rather than manually killing the process to ensure proper cleanup of Quickshell resources and Hyprland registration

Frequently Asked Questions

How do I know if the Omarchy shell is running?

Check for the process and test the IPC endpoint. Run omarchy-shell shell ping in a terminal. If the shell is active, it returns "omarchy-shell is ready". You can also verify the PID file exists at $HOME/.local/state/omarchy/shell.pid and that the process is listed in ps aux | grep omarchy-shell.

Can I restart the shell without losing my Hyprland windows?

Yes. The omarchy-restart-shell script only terminates the Quickshell-based UI layer defined in shell/shell.qml, not the Hyprland compositor itself. Your windows and layout remain intact because the restart affects only the omarchy-shell process that renders widgets and handles IPC, leaving the Wayland session untouched.

Where does Omarchy store the shell process ID?

The active shell PID is written to $HOME/.local/state/omarchy/shell.pid. This file is created by omarchy-launch-shell at startup and referenced by omarchy-restart-shell during shutdown. The state directory also contains lock files that prevent race conditions during restart operations.

What should I do if omarchy-restart-shell hangs?

If the restart script freezes, manually remove the lock file at $HOME/.local/state/omarchy/restart-shell-called and kill any existing omarchy-shell processes using kill -9 $(cat ~/.local/state/omarchy/shell.pid). Then run omarchy-launch-shell directly. This recovers from scenarios where the shell died without cleaning up its lock files.

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