# How Omarchy Integrates with Hyprland Using Shell Commands and IPC

> Discover how Omarchy integrates with Hyprland using shell commands and IPC. Control workspaces, monitors, and layouts with simple commands like omarchy-toggle-bar and omarchy-refresh-config. Learn more now.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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:

```bash

# 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:

```bash

# 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:

```qml
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.