hyprmoncfg: Multi-Monitor Manager for Omarchy

An Omarchy bar panel for hyprmoncfg. Create multi-monitor layouts for Hyprland in a visual editor and switch them automatically on hotplug and lid events.

https://github.com/user-attachments/assets/d3da78df-2280-481b-b38d-a48bb28dc2e6

The film animates a rebuild of the panel that is checked against real captures, with sample displays. Download it in full quality.

Version 2.7 adds Omarchy's Text size slider to the compact view and lets workspace numbers glide between displays when their plan changes. The panel draws your displays as screens on a stage, sizes itself to what it shows, and gives every setting a control that fits it. The companion TUI shares the same design, placement rules and display terminology, with native keyboard-first controls. See the release notes for highlights.

Screenshots show the actual panel with synthetic display/profile data in an isolated capture host, not a live hardware test. The preview above combines two of those renders, the compact panel and the expanded editor, over Omarchy's ristretto wallpaper.

Layout and display controls

Saved profiles

Workspace planning

Automatically match the right layout to the connected monitors

Set your profiles up once. The desk, with the ultrawide on and the laptop panel off. The dock with three screens. The conference room projector at its own resolution and scale. After that you do nothing. Plug the monitors in and the matching profile is applied. Close the lid and the clamshell layout takes over. Undock and your laptop screen comes back at the scale you picked, with your workspaces where you put them.

It knows your monitors apart by make, model and serial, not by which port they are in. Move a cable from HDMI to DisplayPort and your layout still knows which screen is which. Two identical monitors are told apart by reading the DRM connector directly. The lid switch is read from the kernel, including the Apple SMC lid on a MacBook.

A small background service is what watches for this. It catches hotplug, lid and wake events as they happen, including before the bar has started and coming out of a suspend.

What it does

Live controls

• Per-display brightness for the monitor selected on the layout, using Omarchy's own internal-backlight, DDC/CI, and Apple Display support
• Brightness stays live hardware state rather than being stored in layout profiles, and changes made by Omarchy's panel or brightness keys remain compatible
• Text size, the same desktop-wide control as Omarchy's Display panel (shell, GTK apps and terminals together), directly under Brightness. It runs Omarchy's omarchy-display-text-size, is live desktop state rather than part of a profile, and is hidden when that command is not installed

Keyboard controls

• Main pages are now 1 Layout, 2 Workspaces, 3 Profiles; the 2/3 shortcuts have swapped

• Off and mirrored displays have selectable cards; select an off display to edit its Enabled setting

• Profile actions are available with right-click, the visible menu button, or Shift+F10; deletion asks for confirmation

• Use a saved profile directly with a 30-second preview; automatic selection need not be disabled first

• Setup status and Create profile are available in compact and expanded views; the expanded header groups Identify all, Keys, TUI, and Compact without duplicating setup text

• Canvas and Identify use connector, model with whole-inch size, resolution/refresh, scale/position, and workspaces without display numbering or logical desktop dimensions; the inspector separates Model and Panel size

• The inspector shows all hardware details directly; live hardware brightness remains in compact mode only

• The compact view leads with the layout canvas, drawn as lit screens with workspace chips; the expanded panel sizes itself to the displays and rows it shows, with the hardware details under the canvas

• The companion TUI shares the display-summary conventions; standalone TUI Identify remains pending

• The expanded panel mirrors the TUI shortcuts: 1/2/3 switch pages, a applies, s saves, r resets, and ? shows the contextual key guide.

• On the layout, arrows move the selected display; Shift, Ctrl, and Alt preserve the TUI's fine movement and nearest-display snapping

• Profile browsing and workspace settings use the same arrow, Enter, load, edit, and delete keys as the TUI

Layout

• Snap-to-edge arrangement, and the displays beside an output move with it when scale, mode or rotation changes its size
• Per-output scale, checked for whole-pixel sharpness
• Mirroring, rotation and flips
• Positions by hand or by snapping

Colour and signal

• Nine colour management presets, from sRGB through wide gamut to HDR
• Forced HDR, forced wide colour, and ICC profile paths
• 8 and 10-bit depth
• SDR brightness, saturation and transfer curve, with luminance floors and ceilings for SDR and HDR
• Variable refresh rate: off, on, or fullscreen only

The colour inspector follows Hyprland's colour terminology while preserving the underlying fields:

Every editable per-display field gains an individual reset action after it diverges from the loaded profile. Resetting restores that one saved value without discarding unrelated edits. All-zero display luminance overrides leave EDID detection in control.

Neutral SDR multipliers are shown as 1, including profiles that omit them. Resets preserve saved zero/omitted luminance overrides instead of replacing them with generic display defaults. Mode, scale, and rotation resets use the same layout reflow as ordinary edits, so neighboring displays remain aligned.

Profiles and switching

• One profile per place you work, applied automatically on hotplug, lid and resume
• Two identical monitors are told apart, and a layout survives moving a cable to another port
• Previewed changes revert unless you confirm within 30 seconds by default
• Failed automatic applies retry with bounded backoff; all-displays-off startup and failed-wake rescue are not yet complete

Workspaces

• A workspace planner that lays your workspaces out across the displays in a profile: manual, sequential, or interleaved
• When a plan change moves a workspace to another display, its numbered chip glides there on the canvas, so you can see what moved. It follows Hyprland's animations setting and never delays input
• Choose Off when another tool, such as hyprsplit, manages your workspaces: hyprmoncfg then writes no workspace rules for that profile and keeps the plan for when you choose a strategy again
• Set how many workspaces there are, how they group, and the monitor order they follow
• Workspace and group counts have no fixed product cap; type an exact large value directly
• Group size appears only for Sequential plans; type an exact workspace count and press Enter
• In manual mode, move each numbered workspace directly between displays with the row arrows or keyboard
• Per-monitor workspace rules, saved with the profile and applied with it
• Persistence: First per display or All assigned with hyprmoncfg 1.19.0. Manual rules retain their individual persistence flags.

Safer display refresh and identification

Choose Identify in the hardware inspector or Identify all in the header. One persistent service uses a fresh live snapshot, rejects replaced or ambiguous hardware, and cancels obsolete cues on topology changes, backend loss, or preview activity. Identification stays input-transparent and does not apply a layout.

Hotplug refreshes preserve in-progress edits and input. Stale status/editor replies cannot replace a newer topology or preview state; compositor-busy responses retain the last visible snapshot while bounded retries recover.

Editor refreshes wait for an active preview to finish; choosing Discard still resets the draft from a fresh layout.

Install

omarchy plugin add https://github.com/crmne/omarchy-hyprmoncfg.git --enable

If hyprmoncfg is missing, open the panel and choose Install hyprmoncfg. The panel closes before Omarchy opens its presented terminal, so the terminal can receive keyboard input at the password prompt. Installation monitoring continues while the panel is closed. The terminal runs:

if pacman -Q hyprmoncfg-bin >/dev/null 2>&1; then
  yay -S --needed --cleanafter hyprmoncfg-bin
elif pacman -Q hyprmoncfg >/dev/null 2>&1; then
  yay -S --needed --cleanafter hyprmoncfg
else
  omarchy pkg aur add hyprmoncfg-bin
fi
systemctl --user enable hyprmoncfgd.service
systemctl --user restart hyprmoncfgd.service
setsid -f gtk-launch hyprmoncfg-omarchy >/dev/null 2>&1

A fresh install takes hyprmoncfg-bin, the ready-made build; a machine that already has either package keeps it and upgrades it directly through yay (hyprmoncfg builds from source, as the AUR asks of packages under the plain name). Upgrades keep yay interactive so the user can review AUR changes. Both commands run in Omarchy's presented terminal, never invisibly inside omarchy-shell. After a successful install or upgrade it explicitly restarts the daemon, so an already-running service immediately uses the new binary, then opens hyprmoncfg through its hidden Omarchy desktop launcher. That launcher ships with the main package and carries Omarchy's standard TUI.float window identity, so the editor opens centered at the normal floating size without putting Omarchy-specific window logic in the panel. Saving a profile updates the panel immediately over IPC.

Requirements

• Omarchy Quattro with third-party shell plugins
• hyprmoncfg 1.19.0 or newer

Staying up to date

Use Omarchy's standard plugin update command to review and install updates:

omarchy plugin update crmne.hyprmoncfg

The panel does not fetch upstream Git commits, change its checkout, or show a permanent update action when no update has been detected. The marketplace listing records the version and exact commit most recently verified for publication; that verification status is informational and is not an update notification.

Upgrading the hyprmoncfg package is a separate matter: installing runs as root and cannot restart a user service, so the previous daemon keeps serving profiles until someone restarts it. When the running daemon is older than the installed binary, the panel offers Restart daemon. The hyprmoncfg TUI says the same in its status line, where the message is also the button.

Remove

Hand display management back to Omarchy

hyprmoncfg unmanage
omarchy plugin remove crmne.hyprmoncfg

unmanage stops automatic switching, removes the hyprmoncfg include from your Hyprland configuration, hands Omarchy's monitor watcher back, and reloads Hyprland. Omarchy or any other display tool can then control your monitor configuration normally.

The daemon remains enabled and running, but this is intentional and harmless: its persisted unmanaged state prevents it from applying profiles or changing your monitor configuration, and it sits idle without using CPU. Run hyprmoncfg manage if you want it to take control again.

Fully uninstall hyprmoncfg

Stopping and removing the daemon is not required after unmanage. If you nevertheless want to remove hyprmoncfg completely, run the commands above and then:

systemctl --user disable --now hyprmoncfgd.service
omarchy pkg drop hyprmoncfg

Your saved profiles remain in ~/.config/hyprmoncfg/profiles.

Development

The proposed shared workflow and panel direction are documented in DESIGN.md, with an interactive design study. These describe planned improvements, not additional capabilities in the current release.

The confirmation service controls previews it starts itself, and can recover a preview when the daemon reports that its original client disconnected. A live TUI keeps its own confirmation. This recovery requires the daemon's preview.reclaimable status field. The required hyprmoncfg 1.19.0 backend also keeps Omarchy's lock/wake handling aligned with the active laptop scale and position.

After changes to preview handling, test position and scale changes, disabling the panel's own display, keyboard and mouse confirmation, timeout rollback, and opening the TUI while the plugin is enabled. The automated tests exercise socket message ordering; monitor remapping and keyboard focus also need a live session. Also verify that the installer terminal accepts keyboard input, field resets return to their loaded values without discarding other edits, and identical saved layouts show the confirmed current profile consistently.

node --test tests/*.test.js
qmllint *.qml
QT_QUICK_BACKEND=software /usr/lib/qt6/bin/qmltestrunner -platform offscreen -input tests/qml
omarchy plugin validate .
git diff --check