How to Restart the Omarchy Shell: Complete Command Guide

Run omarchy-restart-shell from your terminal to safely terminate the current Quickshell process and launch a fresh Omarchy session while handling lock file cleanup automatically.

The Omarchy desktop environment from basecamp/omarchy renders its user interface through a Quickshell process that maintains state in ~/.local/state/omarchy/. When you need to restart the Omarchy shell after updating QML plugins, editing configuration files, or recovering from a frozen session, using the dedicated restart command ensures proper lock management and prevents race conditions.

Understanding the Omarchy Shell Architecture

The Omarchy shell relies on a file-based locking mechanism to prevent multiple instances from running simultaneously. The shell creates a lock file at $HOME/.local/state/omarchy/shell.lock during startup and removes it upon termination. According to the source code in bin/omarchy-restart-shell, the restart sequence must coordinate with this lock system to avoid conflicts with the Quickshell process manager.

When the shell becomes unresponsive or you modify core QML components, a simple process kill leaves stale lock files that prevent new instances from launching. The omarchy-restart-shell command handles these edge cases by implementing atomic restart locks and stale file detection.

Using the omarchy-restart-shell Command

The primary method to restart the Omarchy shell is the omarchy-restart-shell utility located in bin/omarchy-restart-shell. This script provides a safe wrapper around the shell lifecycle.

The Four-Stage Restart Process

The command executes a deterministic sequence to ensure clean state transitions:

1. Acquire the restart lock – The script creates an atomic lock to prevent concurrent restart attempts from multiple processes.

2. Terminate the current Quickshell instance – It signals the running shell to exit, which triggers cleanup of the shell lock file at $HOME/.local/state/omarchy/shell.lock.

3. Launch a fresh shell – Upon confirmation of the previous process termination, it invokes omarchy-launch-shell to instantiate a new Quickshell session and regenerate the lock file.

4. Fail-safe recovery – If the shell crashed and left a stale lock file, the command detects this condition and forcibly cleans up the orphaned lock before starting the new instance, as verified in [test/shell.d/restart-shell-test.sh](https://github.com/basecamp/omarchy/blob/quattro/test/shell.d/restart-shell-test.sh).

Basic Usage

Execute the restart from any terminal emulator:

omarchy-restart-shell

The command returns only after the new shell has successfully acquired its lock file and initialized the Quickshell runtime.

Scripting and Automation Integration

You can integrate the restart command into configuration reload workflows or update scripts. The bin/omarchy-update-restart script demonstrates this pattern by calling omarchy-restart-shell as part of system update procedures.

Conditional Restart After Configuration Changes

Use this pattern to reload the shell only when custom configuration exists:

if [[ -f "$HOME/.config/omarchy/shell.json" ]]; then
    echo "Reloading Omarchy shell..."
    omarchy-restart-shell
fi

Error Handling in Scripts

When invoking the restart from other Omarchy commands, capture failures gracefully:

omarchy-restart-shell || echo "Failed to restart the shell"

UI Menu Integration

The restart command is exposed through the default application menu defined in default/omarchy/omarchy-menu.jsonc (line 356). Users can trigger a shell restart without opening a terminal by selecting the restart option from the Omarchy menu, which executes omarchy-restart-shell in the background.

Additional documentation appears in [docs/omarchy-shell.md](https://github.com/basecamp/omarchy/blob/quattro/docs/omarchy-shell.md), which describes both manual and programmatic restart methods for the Quickshell-based desktop environment.

Summary

• omarchy-restart-shell is the canonical command to restart the Omarchy shell safely.
• The command manages the Quickshell lock file at ~/.local/state/omarchy/shell.lock to prevent race conditions.
• It implements a four-stage process: acquire lock, terminate old process, launch new shell, and recover from stale locks.
• The restart utility is available in the UI menu and referenced throughout the codebase, including update scripts and automated tests.

Frequently Asked Questions

What is the fastest way to restart the Omarchy shell?

Run omarchy-restart-shell from any terminal. This immediately terminates the current Quickshell process and spawns a new instance without requiring a full system logout. The command handles lock file cleanup automatically, making it faster and safer than manually killing the process.

Where does Omarchy store its shell lock files?

The shell maintains its runtime lock at $HOME/.local/state/omarchy/shell.lock. The restart command checks this location to determine if a Quickshell instance is currently active and removes stale locks if the process crashed without cleaning up its state files.

Can I restart the Omarchy shell if it has crashed?

Yes. The omarchy-restart-shell command includes fail-safe logic to detect and remove stale lock files left by crashed processes. As implemented in the test suite at test/shell.d/restart-shell-test.sh, the command will clean up orphaned locks and launch a fresh shell even when the previous instance did not shut down cleanly.

How do I invoke a restart from the Omarchy menu?

Select the restart option from the default application menu. The menu entry is defined in default/omarchy/omarchy-menu.jsonc at line 356 and executes omarchy-restart-shell in the background, allowing you to restart the desktop environment without opening a terminal window.

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