How Omarchy Integrates with Hyprland Using Shell Commands and IPC

Omarchy integrates with Hyprland through the Quickshell Hyprland module, exposing shell commands like omarchy-toggle-bar and omarchy-refresh-config that dispatch IPC calls to control workspaces, monitors, and window layouts.

The omacom/omarchy repository implements a Qt-based desktop shell that synchronizes its UI state with the Hyprland compositor via declarative QML bindings. By leveraging the Quickshell.Hyprland module, Omarchy translates high-level CLI commands into low-level Hyprland IPC operations, enabling real-time workspace tracking, configuration hot-reloading, and dynamic monitor-aware rendering.

The Quickshell Hyprland Module Foundation

Omarchy’s integration relies on the Quickshell.Hyprland QML module, which exposes Hyprland’s IPC socket as reactive properties. The module provides direct access to workspaces, monitors, and keyboard layouts through singleton objects that QML widgets bind to for live updates.

Key properties available to Omarchy components include:

• Hyprland.workspaces – Array of workspace objects with id and name fields
• Hyprland.focusedWorkspace – Reference to the currently active workspace
• Hyprland.focusedMonitor – The monitor currently receiving input
• Hyprland.monitorFor(outputName) – Lookup function for specific display data

These bindings allow Omarchy widgets to react instantly to Hyprland state changes without polling.

Core Omarchy Commands for Hyprland Control

Omarchy exposes several shell commands that route through the Quickshell Hyprland module to execute Hyprland dispatchers or reload configurations.

Workspace and Monitor Control

The omarchy-toggle-bar command toggles the visibility of the top panel, which internally queries Hyprland.workspaces to render the current workspace list. For direct workspace switching, Omarchy provides wrappers around Hyprland’s dispatch interface:

# Toggle the bar visibility (reads Hyprland workspace state)

omarchy-toggle-bar

# Switch to workspace 5 via IPC dispatch

omarchy-workspace-switch 5

Under the hood, omarchy-workspace-switch invokes the Quickshell method Hyprland.dispatch("workspace 5"), which writes to Hyprland’s socket at /tmp/hypr/{HYPRLAND_INSTANCE_SIGNATURE}/.socket.sock.

Configuration Hot-Reloading

Omarchy maintains user-modifiable Hyprland configurations that can be refreshed without restarting the compositor:

# Refresh Hyprland config from Omarchy defaults

omarchy-refresh-config hypr/hyprland.lua

# Full Hyprland reload (used after package migrations)

omarchy-reload-hyprland

The omarchy-refresh-config command copies default configuration templates into the user’s Hyprland config directory and signals the running Quickshell instance to reparse any dependent UI components.

IPC Routing Architecture

When you execute an Omarchy command, the request flows through a specific stack:

1. CLI Entry Point – Shell scripts in bin/ (e.g., omarchy-toggle-bar) forward arguments to the running Quickshell instance via D-Bus or socket activation
2. Quickshell QML – The main shell process receives the command and invokes methods on the Hyprland singleton (such as exec_cmd or dispatch)
3. Hyprland IPC – Quickshell writes JSON commands to Hyprland’s Unix socket, triggering immediate compositor state changes
4. UI Reflection – QML widgets bound to Hyprland.workspaces or Hyprland.focusedMonitor receive change signals and repaint automatically

Key Source Files and Implementation Details

The integration is implemented across several plugin directories, with each component handling specific Hyprland events or data streams.

Workspace Management Widgets

The file shell/plugins/bar/widgets/Workspaces.qml imports Quickshell.Hyprland and implements the workspace switcher logic:

import Quickshell.Hyprland

// Binding to workspace list
Hyprland.workspaces.forEach(workspace => {
    // Render workspace button
})

This widget reacts to Hyprland.focusedWorkspace changes to highlight the active workspace button synchronously with Hyprland’s internal state.

Monitor-Aware UI Components

In shell/plugins/bar/Bar.qml, the shell uses Hyprland.focusedMonitor to determine which screen should display the bar when multiple monitors are connected. The background plugin at shell/plugins/background/Background.qml extends this by querying Hyprland.monitorFor() to size wallpapers per-display and mirror Hyprland’s decoration:rounding value for UI corner radius consistency.

Input and Idle Event Handling

Keyboard layout switching is handled in shell/plugins/bar/widgets/KeyboardLayout.qml, which listens for Hyprland’s activelayout event to update the indicator text. For power management, shell/plugins/services/idle/Service.qml registers a Hyprland event handler (handleHyprlandEvent) that pauses idle timers when Hyprland emits lockscreen activation signals, preventing the system from sleeping while the screen is locked.

Summary

• Omarchy uses the Quickshell.Hyprland QML module to bind Hyprland’s IPC interface to reactive UI properties.
• Commands like omarchy-toggle-bar and omarchy-workspace-switch route through Quickshell to call Hyprland dispatchers directly.
• Workspace logic resides in shell/plugins/bar/widgets/Workspaces.qml, while monitor detection occurs in shell/plugins/bar/Bar.qml and shell/plugins/background/Background.qml.
• Configuration management commands (omarchy-refresh-config, omarchy-reload-hyprland) update Hyprland’s runtime state without requiring a full session restart.
• Event-driven widgets in KeyboardLayout.qml and Service.qml listen for Hyprland signals to synchronize keyboard layouts and idle inhibition states.

Frequently Asked Questions

What IPC mechanism does Omarchy use to communicate with Hyprland?

Omarchy communicates through the Quickshell.Hyprland module, which abstracts Hyprland’s Unix socket IPC into QML properties and methods. The module handles socket discovery at /tmp/hypr/{HYPRLAND_INSTANCE_SIGNATURE}/.socket.sock and provides methods like dispatch() and exec_cmd() that serialize commands into Hyprland’s JSON IPC protocol.

How do I reload Hyprland configuration through Omarchy?

Use the omarchy-refresh-config command followed by the configuration path, such as omarchy-refresh-config hypr/hyprland.lua. This copies the latest default configuration from the Omarchy package and notifies the shell to refresh its Hyprland-dependent UI components. For a full compositor reload after major updates, run omarchy-reload-hyprland.

Where is the workspace switching logic implemented in the source code?

The workspace UI and its Hyprland bindings are implemented in shell/plugins/bar/widgets/Workspaces.qml. This file imports Quickshell.Hyprland and binds to the Hyprland.workspaces and Hyprland.focusedWorkspace properties to render interactive workspace buttons that reflect the current compositor state.

Can Omarchy commands target specific monitors or displays?

Yes. Omarchy widgets use Hyprland.focusedMonitor to determine the active display and Hyprland.monitorFor(outputName) to query specific monitor geometries. The bar component in shell/plugins/bar/Bar.qml uses these properties to position itself on the correct screen, while background images in shell/plugins/background/Background.qml scale according to individual monitor resolutions reported by Hyprland.

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