# hyprmoncfg — Full Documentation > Documentation for hyprmoncfg, a visual multi-monitor layout editor and automatic profile switcher for Hyprland. --- # Multi-monitor layouts for Hyprland Canonical URL: https://hyprmoncfg.dev/ Create multi-monitor layouts for Hyprland Arrange visually. Save each setup. Switch automatically on hotplug and lid events. [Install hyprmoncfg](/getting-started/) · [See the editor](/what-is-hyprmoncfg/#screenshots) · [GitHub](https://github.com/crmne/hyprmoncfg) · [Terminal Trove Tool of the Week](https://terminaltrove.com/hyprmoncfg/) --- # What is hyprmoncfg? Canonical URL: https://hyprmoncfg.dev/what-is-hyprmoncfg/ ## The problem with Hyprland monitor configuration Configuring monitors in Hyprland means writing `monitor=` lines by hand. A 4K display at 1.33333x scale is effectively 2880x1620 pixels, so the monitor next to it needs to start at x=2880. Vertically centering a 1080p panel against it means doing division in your head to get the y-offset right. You reload, you're off by 40 pixels, you edit, you reload again. There's no visual feedback until after you've committed to a config. Then it gets worse. You unplug your laptop, go to a conference, plug into a projector, and you're back to editing config files backstage before your talk. You come home, dock the laptop, and the layout is wrong again. Existing tools try to help but bring their own problems. Some need a Python runtime and GTK just to draw a layout. Others have no visual editor at all -- profiles are config files you write by hand. Some handle hotplug but break when connectors swap between boots. And none of them check whether Hyprland is actually reading the file they're writing to. ## What hyprmoncfg does differently **A native Omarchy panel and a companion TUI.** The [Omarchy Quattro panel](/omarchy/) provides a graphical layout canvas with drag-and-drop, display and colour controls, a workspace planner, and saved profiles. The terminal editor offers the same shared configuration engine with keyboard and mouse controls. It remains useful from a TTY or over SSH when you need to configure a running Hyprland session without the graphical panel. **One apply engine, everywhere.** The panel sends changes to the daemon. The TUI uses that daemon when it is running, or the same shared engine directly when it is not: write the generated monitor config atomically, reload Hyprland, re-read monitor state, and verify. Previewed changes revert unless you confirm them. **Profiles follow your hardware, not your ports.** Each profile stores monitor identity by make, model, and serial -- not by connector name. `DP-1` and `DP-2` can swap all they want. Your layout holds. **It verifies the generated config is loaded.** Legacy source chains are checked before writing. For Hyprland 0.55+ Lua configs, hyprmoncfg reloads Hyprland and asks the active Lua state to confirm that the generated monitor file actually ran. If it did not, hyprmoncfg rolls the file back. **A small shared backend.** The core ships as two compiled Go binaries for Hyprland. The graphical panel uses Omarchy's existing Quickshell environment. Optional hardware features use their own integrations, such as iio-sensor-proxy for automatic rotation on a tablet or 2-in-1. ## How it compares | | hyprmoncfg | Monique | HyprDynamicMonitors | HyprMon | nwg-displays | kanshi | |---|---|---|---|---|---|---| | GUI or TUI | Native Omarchy GUI + TUI | GUI | TUI | TUI | GUI | CLI | | Spatial layout editor | Yes | Yes | Partial | Yes | Yes | No | | Drag-and-drop | Yes | Yes | No | Yes | Yes | No | | Snapping | Yes | Not documented | No | Yes | Yes | No | | Profiles | Yes | Yes | Yes | Yes | No | Yes | | Auto-switching daemon | Yes | Yes | Yes | No (roadmap) | No | Yes | | Workspace planning | Yes | Yes | No | No | Basic | No | | Mirror support | Yes | Yes | Yes | Yes | Yes | No | | Safe apply with revert | Yes | Yes | No | Partial (manual rollback) | No | No | | Hyprland 0.55 Lua config | Yes | No | No | Yes | Yes | N/A | | Include-chain verification | Yes | No | No | No | No | No | | Additional runtime dependencies | Omarchy Quickshell for the panel; optional hardware integrations | Python + GTK4 + libadwaita | UPower, D-Bus | None | Python + GTK3 | None | ## Demo Plug in your monitors, arrange them once, save the arrangement as a profile, and it comes back whenever those monitors do. The film animates a rebuild of the TUI that is checked against real captures, with sample displays. ## Screenshots Captured from the 1.19 TUI with isolated synthetic displays and profiles, in light and dark terminal themes. These are actual renderer captures, not mockups or evidence of physical hotplug testing. ### Dark theme [Layout editor (dark) Layout editor](/assets/images/screenshots/layout-dark.png) [Save profile dialog (dark) Save profile dialog](/assets/images/screenshots/save-profile-dark.png) [Profiles tab (dark) Profiles tab](/assets/images/screenshots/profiles-dark.png) [Workspaces tab (dark) Workspace planner](/assets/images/screenshots/workspaces-dark.png) ### Light theme [Layout editor (light) Layout editor](/assets/images/screenshots/layout-light.png) [Save profile dialog (light) Save profile dialog](/assets/images/screenshots/save-profile-light.png) [Profiles tab (light) Profiles tab](/assets/images/screenshots/profiles-light.png) [Workspaces tab (light) Workspace planner](/assets/images/screenshots/workspaces-light.png) --- # Getting Started: Hyprland monitor setup Canonical URL: https://hyprmoncfg.dev/getting-started/ ## Install ### Arch Linux ```bash yay -S hyprmoncfg-bin ``` ```bash yay -S hyprmoncfg-git ``` ### Fedora COPR ```bash sudo dnf copr enable paolino/hyprmoncfg sudo dnf install hyprmoncfg ``` ### Nix / NixOS ```bash nix run nixpkgs#hyprmoncfg nix profile install nixpkgs#hyprmoncfg ``` ```nix environment.systemPackages = with pkgs; [ hyprmoncfg ]; ``` ### Gentoo GURU ```bash sudo eselect repository enable guru sudo emaint sync -r guru sudo emerge gui-apps/hyprmoncfg ``` ### Void Linux Unofficial [Blackhole-vl](https://github.com/Event-Horizon-VL/blackhole-vl): ```bash printf 'repository=https://mirror.black-hole.dev/%s/\n' "$(uname -m)" | sudo tee /etc/xbps.d/00-repository-blackhole.conf sudo xbps-install -S sudo xbps-install -S hyprland hyprmoncfg ``` ### Build from source ```bash git clone https://github.com/crmne/hyprmoncfg.git cd hyprmoncfg go build -o bin/hyprmoncfg ./cmd/hyprmoncfg go build -o bin/hyprmoncfgd ./cmd/hyprmoncfgd ``` ### Install to `~/.local/bin` ```bash install -Dm755 bin/hyprmoncfg ~/.local/bin/hyprmoncfg install -Dm755 bin/hyprmoncfgd ~/.local/bin/hyprmoncfgd ``` ## Configure Hyprland hyprmoncfg needs: - A running Hyprland session - `hyprctl` in `PATH` - A Hyprland config that includes hyprmoncfg's generated monitor file For legacy hyprlang configs, most setups already have this in `~/.config/hypr/hyprland.conf`: hyprmoncfg writes a file it creates and owns, `~/.config/hypr/hyprmoncfg-monitors.lua` (or `.conf` on legacy configs), and adds one line at the end of your root Hyprland config to load it: ```lua dofile(os.getenv("HOME") .. "/.config/hypr/hyprmoncfg-monitors.lua") ``` Loading last is what makes an applied layout final: any monitor rule Hyprland reads afterwards would override it. You do not need to add the line yourself, and nothing you wrote is replaced -- a `monitors.conf` or `monitors.lua` of your own is left alone. `hyprmoncfg doctor` reports the current state if you want to check. If your Hyprland config is managed by a dotfile tool such as chezmoi or stow, keep that line in your source copy. Otherwise your dotfile tool and hyprmoncfg will keep undoing each other. Hyprland does not read the generated file automatically, so on apply hyprmoncfg reloads Hyprland and asks the active Lua state to confirm that the file actually ran. If it did not, hyprmoncfg restores the previous file rather than leaving you with a layout that silently did nothing. If your config files live somewhere other than the defaults: ```bash hyprmoncfg --monitors-conf /path/to/monitors.conf --hypr-config /path/to/hyprland.conf hyprmoncfg --monitors-conf /path/to/monitors.lua --hypr-config /path/to/hyprland.lua ``` ## Create your first profile Launch the TUI: ```bash hyprmoncfg ``` ![Layout editor](/assets/images/screenshots/layout-dark.png) You land on the layout tab. The left side shows your connected monitors as rectangles arranged the way Hyprland currently sees them. The right side keeps hardware information above focused **Display** and **Color** controls for the selected monitor. Drag monitors on the canvas to rearrange them. Click **Display** or **Color** in the pane border, then select a field to change resolution, scale, position, or color behavior. When the layout looks right: 1. Press `s` to save 2. Type a name like `desk` or `home-office` 3. Press `Enter` That's it. Your monitor layout is now a named profile. ## Apply a saved profile ```bash hyprmoncfg apply desk ``` Your monitors rearrange immediately, and a 10-second countdown starts. If the layout looks right, press any key to confirm. If something looks wrong, just wait -- it reverts automatically. This is the same safety mechanism you see on TVs and projectors when you change the resolution. For scripts and automation, skip the countdown: ```bash hyprmoncfg apply desk --confirm-timeout 0 ``` ## Enable automatic switching The daemon watches for monitor changes and applies the best matching profile automatically. Set it up once and forget about it. > **Clean Up Before You Enable The Daemon** > > `hyprmoncfgd` scores **every** profile in `~/.config/hyprmoncfg/profiles/`. Old experiments, duplicate layouts, and half-finished saves are part of matching until you delete them. Before you turn on automatic switching, make sure your profile library reflects real setups you actually want auto-applied: - Save one profile for each real desk, dock, projector, or travel setup you use - Delete throwaway profiles you created while experimenting - Re-save the profile you actually use instead of keeping old variants around On laptops, you do not need a separate closed-lid profile. Save the profile for the monitors you attach at that desk. When the lid is closed and an external monitor is connected, hyprmoncfg forces the internal laptop panel off for the apply and moves workspaces away from it. AUR, Fedora COPR, Nixpkgs, and Gentoo GURU: ```bash systemctl --user daemon-reload systemctl --user enable --now hyprmoncfgd ``` Void Linux with Blackhole-vl, in legacy `hyprland.conf`: ```text exec-once = hyprmoncfgd ``` Void Linux with Blackhole-vl, in `hyprland.lua`: ```lua hl.on("hyprland.start", function() hl.exec_cmd("hyprmoncfgd") end) ``` Manual install: ```bash mkdir -p ~/.config/systemd/user cp packaging/systemd/hyprmoncfgd.local.service ~/.config/systemd/user/hyprmoncfgd.service systemctl --user daemon-reload systemctl --user enable --now hyprmoncfgd ``` Now when you plug in a monitor, unplug one, dock your laptop, or close the lid, the daemon finds the profile that best matches your current hardware and applies it. No interaction needed. The packaged systemd service works with both config formats because the daemon detects the active Hyprland config and writes the matching generated file through the same apply engine as the TUI. If the daemon ever applies a layout you didn't expect, the most common cause is stale or duplicate profiles in `~/.config/hyprmoncfg/profiles/`. The daemon scores every profile it finds, not just the ones you remember saving. Delete old experiments, keep one profile per real setup, and the matching becomes predictable. See [Daemon Behavior](/daemon/) for the full scoring breakdown. ## Add profiles to your dotfiles Profiles are stored in `~/.config/hyprmoncfg/profiles/`. Each profile has a canonical JSON file plus generated `.conf` and `.lua` sidecars, so you can keep the layouts as plain Hyprland snippets even if you stop using hyprmoncfg. Add the whole config directory to your dotfile manager and your layouts roam across every machine. With [chezmoi](https://www.chezmoi.io/): ```bash chezmoi add ~/.config/hyprmoncfg ``` Your desk at home, your laptop bag setup, your conference projector layout -- all versioned, all portable. The daemon on each machine picks the right profile based on what's actually plugged in. You never commit the generated `~/.config/hypr/hyprmoncfg-monitors.{conf,lua}`. You commit your profiles. hyprmoncfg writes it for you. Do commit the one include line it adds to your Hyprland config, so your dotfile tool and hyprmoncfg stop undoing each other. ## Next steps - [TUI Walkthrough](/tui/) -- learn the full editor interface - [Daemon Behavior](/daemon/) -- understand how auto-switching works - [Dotfiles Integration](/dotfiles/) -- set up profile portability - [Command Reference](/commands/) -- every flag and subcommand --- # TUI Walkthrough Canonical URL: https://hyprmoncfg.dev/tui/ ## Layout editor At narrow widths, footer Apply/Save/Keys actions take priority over project links and build information. The Workspaces planner includes Persistence: First per display (default) or All assigned. Manual plans display Custom (per rule) and preserve individual flags. When you launch `hyprmoncfg`, you land on the layout tab. This is where you arrange your monitors and tune their settings. The screen is split into two panes: - **Left**: a stage showing your monitors as draggable screens on a dotted field, positioned the way Hyprland currently sees them, with the selected display's **Hardware** facts directly below it - **Right**: switchable **Display** and **Color** controls -- resolution, scale, position, transform, VRR, color management, and more Display cards consistently show connector, model with whole-inch size (`32"`), `3840x2160@144Hz`, `Scale 1.33x Position 0,0`, and workspace IDs. The connector and model sit at the top of the card with the workspace IDs as chips beside the connector; the mode and the scale and position sit on the card's bottom rows. The selected card has a heavy border. There are no arbitrary display numbers or logical desktop dimensions. Small cards prioritize identity and workspaces. Formatting never rounds the stored mode or scale. Lists outside the canvas, such as the workspace plan, keep the `1, 2, 3` form. The Hardware box shows connector, model, and maximum advertised resolution, panel dimensions, type, and serial, all shown directly without a More details action. It uses two columns when the stage is wide enough. In narrow terminals the stage, Hardware, and the controls stack, and the stage takes only the rows its arrangement needs, so the controls keep the rest. The TUI currently has no standalone on-screen Identify overlay; this remains a panel capability, not a requirement to install Omarchy for the TUI. Panel size shows a whole-inch diagonal and exact reported dimensions, such as `32" (710x400mm)`, separately from the inspector's model name. Drag monitors on the canvas to reposition them. The information and controls update in real time. When you need pixel-perfect placement, use the `Position X` and `Position Y` fields in **Display** instead of dragging. While the TUI is open, it also refreshes live monitor state in the background. Plugging or unplugging a monitor, docking, undocking, or changing lid state reloads the editor so the canvas matches the current hardware. The canvas only draws displays that are on and not mirroring another one. Off and mirrored displays have separate bracketed rows above the geometry, showing connector, state, and model. Click a row to inspect it; click **Enable** to turn an off display on in the draft. Keyboard users can select it with `[` / `]` and press `Space`. This does not apply the draft. Missing hardware says **Not connected** without an Enable action. In crowded layouts, keyboard selection reveals hidden rows without covering the active display cards. A display that is on but has no mode shows nothing, so it gets a row too, marked **No usable signal**, instead of an empty rectangle. When `hyprmoncfgd` runs a display below its saved settings because it would not stay on at them, that display's card says how it runs now, for example `running at 120 Hz without VRR`. The saved profile is unchanged. See [Daemon Behavior](/daemon/#displays-that-wont-stay-on). ![Layout editor](/assets/images/screenshots/layout-dark.png) ### Main controls | Key | Action | |-----|--------| | `1` `2` `3` | Switch tabs (layout, workspaces, profiles) | | `a` | Preview the current draft or selected profile, then Keep or Revert | | `s` | Save current draft as a named profile | | `r` | Reset from live Hyprland state | | `?` | Show every key for the tab you are on | | `q` | Quit | ### Canvas controls | Input | Action | |-------|--------| | Mouse drag | Move the selected monitor | | Arrow keys | Move by 100px | | `Shift` + arrows | Move by 10px | | `Ctrl` + arrows | Move by 1px | | `Alt` + arrows | Snap beside the nearest enabled monitor | | `0` | Move the selected monitor to 0,0, where Hyprland's own `position = auto` starts | | `[` `]` | Select the previous or next monitor | | `Tab` `Shift+Tab` | Move between the canvas, **Display**, and **Color** | Edits never make displays overlap, and the canvas follows the same placement rules as the Omarchy panel: - **Drag** a display and it follows the pointer; the stage holds still until you let go. On release it snaps to a neighbour's edge or alignment within about one canvas row. Dropped on top of another display, it moves to the nearest clear edge instead. - **Arrow keys**, **Position X/Y**, and `0` use the requested position when clear. If occupied, the display moves to the nearest clear outside edge. - `Alt` + arrows place the selected monitor beside the nearest enabled monitor; any collision with a third display is resolved the same way. - Enabling a display automatically finds room when its old position is occupied, so it returns to the canvas and can be moved again. Mode, scale, and rotation changes preserve attached neighbours first, then resolve remaining collisions. - Existing overlaps are cleared during geometry edits. Disabled displays and mirrors do not reserve space. Saved profiles change only when you save. When a preview turns a previously disabled display on, it also wakes that output and checks that Hyprland reports it awake before showing confirmation. A failed wake rolls back instead of accepting a black display as successfully enabled. Other displays that were already enabled but sleeping are left asleep. ### Display and Color controls Press `Enter` on any **Display** or **Color** field to edit it: - **Enabled**, **Refresh**, **VRR**, **Color depth**, **SDR EOTF**, **WCG capability**, and **HDR capability** are choice rows, like the scale pills in Omarchy's own Display panel: every option is visible, `←` `→` or `h` `l` move one option and stop at the ends, `Enter` advances and wraps, and a click picks one directly. A row too narrow for its options shows the selected value and still steps - **Resolution** opens a list of the display's resolutions, largest first; `←` `→` step through it. Changing the resolution keeps the refresh rate when the new resolution offers it, and otherwise picks its highest rate - **Refresh** is a choice row of the rates the current resolution offers, such as `60Hz` `120Hz` `144Hz`. It steps like the other choice rows. Resolution and Refresh together set the one stored mode, and cards still show it as `3840x2160@144Hz` - **Scale** is a row of pills like Omarchy's own scale row: 1x, 1.25x, 1.5x, 1.6x, 2x, and 3x (plus 4x on modes at least 5120 pixels wide), each moved up to the next scale that gives whole logical pixels on this display, so a preset can read 1.6x or 3.2x, and presets that land on the same scale show once. The same pills appear in the Omarchy panel. The pills stay the same whatever the scale: a current scale that is not a preset is shown on the last pill instead of **More…**, as `1.33x…`, marked ⚠ Blurry when it is not sharp (its logical size has fractional pixels), and never rewritten. `←` `→` step through every sharp scale from 1x to 4x, the list the panel uses. **More…**, `Enter`, or a click on the Scale label opens that full list, whose **Custom…** types any exact scale in a dialog that says whether it is sharp or Blurry and offers the closest sharp scale, which `Enter` applies. Wide terminals wrap the pills; narrow ones keep one line and slide it, with ‹ and › marking more - **Position X** and **Position Y** are typed in place on their row, so the stage stays visible; `←` `→` move by 10px and `Shift` + `←` `→` by 1px. Snapping stays on the canvas with `Alt` + arrows - **Rotation** cycles with `←` `→` or opens a picker with Enter. On a 2-in-1 or tablet with an orientation sensor, a built-in panel's picker starts with **Auto**, which turns the panel with the device and keeps its current rotation as upright; `←` `→` then change that upright rotation. Press `L` anywhere to lock or unlock automatic rotation. See [2-in-1s and tablets](../two-in-one/) - **Mirror** lets you mirror the selected monitor to any other connected display. For a crisp image, set the mirrored monitor's Resolution to match the source resolution. If the resolutions don't match, Hyprland upscales the image, which looks blurry The **Color** tab uses the same terminology as the Omarchy panel. **Color space / EOTF** combines the primaries and transfer function (for example, **BT.2020 + PQ (HDR)**). The picker shows descriptive labels but saves Hyprland's original values, such as `hdr`. **SDR luminance scale** and **SDR saturation scale** are unitless SDR-to-HDR multipliers, not physical brightness controls. An omitted or zero multiplier uses the neutral value `1`. Black, white, peak, and frame-average luminance are measured in **cd/m²**. Display luminance and WCG/HDR capability fields override display metadata; leave them at their defaults to use EDID. Narrow terminals shorten the labels without changing their meaning. ## Keep or Revert Every preview ends in a **Keep this layout?** (or **Keep this profile?**) dialog. It names what is live, says when the previous layout returns, and drains a countdown meter that ends in the seconds left, so the countdown does not rely on color. When the terminal has rows to spare, a miniature of the arrangement being kept sits under the meter. **[Revert]** and **[Keep]** are buttons you can click; `Enter` or `y` keeps, `Esc` or `n` reverts. The daemon's deadline is authoritative; the dialog only shows it. On short terminals the dialog drops its spacing so both buttons stay on screen. ## Save dialog Press `s` from the layout tab. You'll see a text input and the list of existing profiles. - Type to filter existing profiles - Arrow keys to select one (overwrites after confirmation) - Type a new name and press `Enter` to create a fresh profile ![Save profile dialog](/assets/images/screenshots/save-profile-dark.png) ## Profiles The third tab lists every saved profile and how well it fits the displays that are plugged in right now. **Automatic profile selection** has its own compact box above the left-hand profile list, matching its width. The details column starts at the top alongside it. Click its On/Off control to change automatic matching. The **Saved Profiles** box contains only the table and its actions: Preview, Edit, Rename, and Delete stay pinned below the scrolling list and act on the highlighted row. Profile details remain alongside the list, or below it in narrow terminals. - **Match** is the profile's score against the connected hardware, the same score the daemon uses to pick a profile automatically. A dash means the profile has no display in common with what is connected - **active** marks the profile your screens are already showing - **best** marks the highest scoring profile -- the one the daemon would apply on the next hotplug Selecting a profile fills the right side: its monitor arrangement on top, its details below. The details spell out the score as the arithmetic that produced it, so a surprising number is never a mystery, and they list what the canvas cannot draw -- displays the profile keeps off and displays that mirror another one. On the canvas, a display the profile expects but cannot find is outlined and labelled `not connected`. ![Profiles tab](/assets/images/screenshots/profiles-dark.png) | Key | Action | |-----|--------| | `↑` `↓` | Select a profile | | `Enter`, `a` | Preview the profile, even with automatic selection on | | `l` | Load the profile into the layout editor | | `e` | Edit the profile's post-apply command | | `r` | Rename the profile. Nothing is applied. An older daemon hides this, and `r` keeps resetting from live state | | `d` | Ask to delete the profile; `y` or **[Delete profile]** confirms, Enter, Esc, or **[Cancel]** cancels | | `s` | Save the current draft | **Post-apply command** is the final profile detail. Click its **Edit command** button or its heading to edit it; `e` provides the same operation. Selection uses highlighting without an extra arrow. The profile action context menu remains a panel-only affordance for now; the TUI has visible **Preview**, **Edit**, **Rename**, and **Delete** buttons acting on the highlighted profile, with keyboard shortcuts listed in the footer and help. Selection alone does not apply it. The Status column distinguishes the active or best match from the row currently selected for inspection. ## Workspace planner The second tab lets you distribute workspaces across monitors. **Strategy** is the first row: pick Off or one of three plans. Sequential is preferred for new plans. When importing consecutive rules from one display, the editor uses Sequential with groups of three and keeps the existing workspace total and persistence. Saved profiles retain their explicit strategy, including Interleaved; this default does not migrate existing profiles. | Strategy | What it does | When to use it | |----------|-------------|----------------| | Off | Writes no workspace rules. The profile keeps its plan, so choosing a strategy again brings it back | Another tool manages workspaces, such as [virtual-desktops](../virtual-desktops/) or hyprsplit | | `sequential` | Groups workspaces in chunks (e.g., 1-3 on monitor A, 4-6 on monitor B) | You think of each monitor as having "its own" workspaces | | `interleave` | Round-robins workspaces across monitors (1 on A, 2 on B, 3 on A, ...) | You want next/previous workspace to alternate screens | | `manual` | Shows every workspace as an assignment you can move between monitors | You need full control over exactly which workspace lives where | You can also configure: - **Max workspaces** -- how many workspaces to generate rules for - **Group size** (sequential only) -- how many consecutive workspaces to assign to each monitor before moving to the next. With 2 monitors and a group size of 3, monitor A gets 1-3, monitor B gets 4-6, and so on - **Monitor order** -- which monitor gets the first batch of generated workspaces. Applied assignments preserve this order when the editor reads the live configuration back, independently of the monitors' physical positions. Save the profile to reuse it later. - **Workspace → display** (manual only) -- select a workspace and press `←` or `→` to assign it to a different monitor While the strategy is Off, the other rows show `—` and the workspace plan is empty. There is no fixed workspace or group-size limit. Select **Max workspaces** or **Group size** and press `Enter` to type an exact count; `←` and `→` still make one-step adjustments. Long manual lists stay navigable: the mouse wheel scrolls three rows at a time, `Page Up` and `Page Down` move by a visible page, and `Home` and `End` jump to the first or last row. Only the visible assignment rows are rendered. Switching from a generated strategy to `manual` starts with the plan already on screen, so you can adjust only the exceptional workspaces instead of rebuilding the whole layout. In manual mode, changing **Max workspaces** adds or removes numbered workspace assignments. The right side previews the result twice: **Monitor Layout** paints the workspaces onto the monitors themselves as chips, and **Workspace Plan** below it lists which workspaces each monitor owns. Both update as you change the strategy, so you can see where workspace 1 lands before you save. The workspace plan is stored inside each profile. When the daemon applies a profile, it applies workspace rules too -- layout and workspace assignment in one shot. ## Laptop lids Internal laptop panels are marked as internal displays in the layout view. The TUI also shows the current lid state when it is available. Profiles are still profiles for the attached monitor setup, not separate open-lid and closed-lid variants. The closed-lid policy only forces internal laptop panels off when a real external output already has a usable, awake mode and the target profile keeps it enabled. A modeless dock output, sleeping display, or synthetic fallback does not qualify. Workspace rules move away from a forced-off panel. Interactive previews default to 30 seconds after verification. Confirming a saved profile pauses automatic selection for the current display setup. There is no need to turn automatic selection off before starting a preview. --- # Daemon Behavior Canonical URL: https://hyprmoncfg.dev/daemon/ ## Why a daemon You save profiles with the TUI. But who applies them when you're not looking? That's what `hyprmoncfgd` does. It runs in the background, watches for monitor hotplug and lid events, and applies the best matching profile automatically. Plug in a monitor, close the lid, undock your laptop, connect to a projector -- the daemon handles it. On Omarchy releases that start `omarchy-hyprland-monitor-watch`, the daemon takes exclusive ownership of monitor state. It stops the watcher's exact transient user scope, keeps later copies suppressed, and starts the watcher again when `hyprmoncfgd` exits while Hyprland is still running. This prevents Omarchy's clamshell reconciliation from overwriting an active hyprmoncfg profile. > **Static Configs On Omarchy** > > A generated monitor config cannot provide runtime process ownership by itself. If you use a generated `monitors.lua` without running `hyprmoncfgd`, Omarchy’s monitor watcher remains active and may reconcile the laptop panel using Omarchy’s own settings. Disable that watcher separately or run the daemon. This is especially useful if you move between setups regularly. A conference projector, a coworking space monitor, your desk at home -- each one has different resolution, position, and scale requirements. Save a profile once, and the daemon takes care of it from then on. ## Setup AUR, Fedora COPR, Nixpkgs, and Gentoo GURU: ```bash systemctl --user enable --now hyprmoncfgd ``` Void Linux with Blackhole-vl: ```text exec-once = hyprmoncfgd ``` Manual install: ```bash mkdir -p ~/.config/systemd/user cp packaging/systemd/hyprmoncfgd.local.service ~/.config/systemd/user/hyprmoncfgd.service systemctl --user daemon-reload systemctl --user enable --now hyprmoncfgd ``` That's it. The daemon is running. The rest of this page explains how it decides which profile to apply and how to troubleshoot it. ## How it works When the daemon detects a monitor or lid-state change, it runs through these steps: 1. Read the current monitor set from Hyprland 2. Score every saved profile against the connected hardware (see [Profile matching](#profile-matching) below for how scoring works) 3. Pick the highest-scoring profile 4. If the lid is closed and an external monitor is already usable and will remain enabled, force internal laptop-panel outputs off for this apply 5. Write the active generated monitor file atomically (temp file + rename, so a crash mid-write can't corrupt your config) 6. Tell Hyprland to reload 7. Re-read monitor state and verify the result matches what was intended If the winning profile is the same one that's already applied, the daemon skips re-applying it. If it does reapply, for example after the displays wake, and the generated file would come out identical while the displays already match, it skips steps 5 and 6. You won't see unnecessary reloads. An output absent from a non-strict profile is added to its right edge, vertically centered against the adjacent independent display using logical dimensions. For simultaneous arrivals, each new display becomes the next neighbor. The backend chooses the greatest advertised pixel area, then the highest refresh at that resolution, with VRR off and 8-bit sRGB. Existing output settings and an enabled workspace plan are preserved; the saved profile is not overwritten. Physical-size scale recommendations and explicit failed-wake/cold-start rescue remain separate follow-up work. When no saved profile matches, usable live displays keep their mode, position, rotation, scale and color settings. VRR and bit depth use the same values as a newly added display (VRR off, 8-bit), because Hyprland reports whether VRR is active and the current buffer format rather than the configured settings. Existing workspace assignments are imported. Only modeless or disabled displays need an automatic extended layout; an overlapping initial arrangement is rebuilt rather than preserved. Hyprland's synthetic `FALLBACK` output is never part of it. When Hyprland reports a display at another mode and then stops answering, it is usually still switching that display, for example a built-in panel it is turning on. Verification then waits up to three more seconds for the requested mode before it rejects the layout. If verification rejects a layout and rollback restores the previous configuration and leaves every intended display usable, the daemon pauses automatic attempts for that same request and restored state. This prevents repeatedly switching between a rejected mode and a working one. Editing the profile, changing the display state or workspace rules, or explicitly running `hyprmoncfg manage` or turning automatic profile selection on permits another attempt. Confirmed previews also clear the pause. VRR activity and scanout buffer format changes do not clear it. The pause is held for the running daemon session and logged as `automatic retry paused`; it does not rewrite saved profiles. A rejection whose rollback failed keeps retrying. A compositor that stops answering after it has already reported a mismatch still counts as a rejection, not a busy compositor. Attempts to restore saved settings from a recovery fallback are exempt from this pause: they return to the fallback and schedule another attempt. Other failed automatic applies retry independently of monitor-change events, starting after 2 seconds with capped exponential backoff up to 30 seconds. Transient busy reads and writer contention retry after the normal debounce interval. Successful application stops retries. Preview ownership defers retries; suspend, intentional display sleep and unmanaged mode stop them. Resume or a later wake/topology event restarts reconciliation. Verification reports all failed outputs, not just the first. Monitor/workspace discovery queries have a 750ms timeout. This does not prove physical projector readiness. Resuming or opening the lid is a request for light. When displays still report DPMS off right afterwards, the daemon treats it as a wake that did not take and repeats it up to three times before treating the displays as asleep by choice. It stops early once every enabled display in the layout is awake, so a lit laptop panel doesn't end the wake while an external display is still off. After three retries it stops, and the awake displays stay usable. If the built-in panel is off while the lid is open (it was switched off with the lid shut and the external stayed asleep), the daemon applies the profile anyway, so the panel comes back without waiting for the external. The wake command uses the Lua or legacy syntax Hyprland last reported, even when Hyprland is too busy to answer right after resume. ### Workspaces when a display comes back When a display turns off, Hyprland moves its workspaces to the others. When it comes back, Hyprland would show its default workspace. If the profile plans workspaces, the daemon shows the workspace that display last showed instead, for example workspace 2 rather than 1, after applying the layout. Focus and the cursor go back to the display and position they were on. It remembers the last workspace of each display by hardware identity, while the daemon runs. A workspace that another display is showing, or that the profile assigns to another display, stays where it is. Displays with identical descriptions can't be told apart, so they keep Hyprland's choice. With the workspace planner set to Off, the daemon doesn't touch workspaces at all. ### Displays that won't stay on Some displays can't wake straight into a demanding mode such as 4K at 144 Hz. They drop off the link a second or two after connecting. When they come back, they show "No signal" and go back to sleep. Woken at about 60 Hz and switched to the saved mode once awake, they work. So when a display drops within 4 seconds of connecting at its saved settings, the daemon remembers that it needs a gentle wake: 1. While the display is disconnected, its rule in the generated config wakes it at the refresh rate closest to 60 Hz, at the same resolution, with VRR off. This also happens immediately after the last display disconnects, so the first display can reconnect using its wake rule without waiting for recovery. 2. Once it has stayed connected with a usable mode for 10 seconds, the daemon switches it to its saved settings. Displays that come up cleanly never drop, so they keep coming up in one step. If that switch makes the display drop again within 8 seconds, the daemon steps its settings down one at a time to obtain a working fallback: 1. VRR off. 2. The next lower refresh rate at the same resolution, for example 144 Hz to 120 Hz. 3. The refresh rate closest to 60 Hz. The same steps apply to a display that comes back from sleep enabled but without a mode twice in a row. After a display at reduced settings reports a usable, awake mode for 10 seconds, the daemon tries its saved refresh rate and VRR again. If that attempt is rejected or the display drops right after it, recovery returns to the fallback and waits twice as long before the next attempt (20 seconds, then 40, up to 5 minutes), because each attempt blanks a working display. The wait resets once the saved settings hold, or when the daemon restarts. This also applies to fallbacks caused by a display dropping after a switch. Each attempt finishes before another begins, and recovery stops once the requested settings work. Sleep, suspend, removal, unmanaged mode and previews defer recovery. Resolution, scale and position never change, so other displays and windows stay where they are. The saved profile never changes either. `hyprmoncfg status` names each stepped-down display and how it runs now, and the daemon log says why. The gentle wake and the steps are remembered per display in `~/.config/hyprmoncfg/display-fallbacks.json`, so a restart doesn't repeat the struggle. Confirming any layout clears the steps, so the next switch tries the saved settings again. It keeps the gentle wake, because that still ends at the saved settings. Editing the saved mode or VRR of a display also clears its steps. To forget a gentle wake, delete the file and restart the daemon. Displays with the same description can't be told apart here, so they are never changed. The daemon also can't see a display that stays connected but shows nothing, because Hyprland and the kernel report that the same as a working one. The gentle wake exists because the drop before that silence is visible. ### Displays stuck without a mode aquamarine 0.15.0, the display library under Hyprland 0.56, never releases the kernel's display pipe (CRTC) of a monitor that disconnects. When a monitor comes back and is handed that pipe, the kernel rejects every mode: Hyprland lists it at `0x0` and it stays black or frozen. It typically happens when every monitor was turned off and one comes back alone, or when two monitors come back close together and each is handed the other's pipe. aquamarine 0.15.1 fixes it ([hyprwm/aquamarine#386](https://github.com/hyprwm/aquamarine/issues/386), [#428](https://github.com/hyprwm/aquamarine/issues/428)). The daemon recognises it: an awake monitor stays at `0x0` although it lists modes, while `/sys/class/drm/card*-*` shows a disconnected connector as still `enabled`. It logs the cause, does not step the monitor's settings down, and switches to a free console and back through systemd-logind, then reloads Hyprland. The console switch makes Hyprland reset the kernel's display state. You see a text console for about two seconds. If the monitor is still stuck, the next switch waits 30 seconds, then twice as long each time, up to 10 minutes. When two monitors come back close together and each is handed the other's pipe, both stay at `0x0` while both are connected. A console switch doesn't clear that: Hyprland keeps the swapped pipes, and the screens go on showing the console's last image. The daemon logs it instead, and doesn't step the monitors' settings down. Turn one of the two monitors off, wait 5 seconds, and turn it on again: with it off, the daemon recovers the other one, and the one you turn back on gets a free pipe. logind allows this without root for the active local session. If it refuses, the log says so; switch by hand with `sudo chvt 2`, then `sudo chvt 1` (use the console your session runs on, `loginctl show-session $XDG_SESSION_ID -p VTNr`), or update aquamarine. ## Profile matching Profiles are matched by hardware identity (make, model, serial) -- not connector name. This means your layout survives when monitors swap between `DP-1` and `DP-2` across reboots. Each profile is scored against the currently connected monitors: | Condition | Points | |---|---| | Monitor enabled in profile and connected | +100 | | Monitor disabled in profile but connected | +50 | | Connected monitor not in the profile | −20 | | Monitor enabled in profile but not connected | −30 | | Monitor disabled in profile and not connected | −10 | With the lid closed and an external display connected, the built-in panel scores the other way round, because the closed-lid policy turns it off whatever the profile says: | Condition, lid closed | Points | |---|---| | Built-in panel kept off in the profile | +100 | | Built-in panel turned on in the profile | +50 | So a profile you saved for working with the lid closed wins over an otherwise identical profile that turns the panel on. Without an external display, the panel is scored as usual. For automatic switching, a profile must enable at least one connected display and have a positive score. A partial match can provide the base for a temporary extended layout: unfamiliar displays are added unless the profile explicitly sets `disable_unknown_outputs: true`. Deliberately disabled known displays remain off. Missing saved displays remain allowed, so undocking can still restore the laptop layout. Among eligible profiles, the highest score wins. Ties break alphabetically by profile name. A profile that mentions a monitor which is not plugged in pays for it either way, so the profile that describes exactly the connected displays beats a larger profile that happens to include them. The profiles tab shows every score, along with this breakdown for the selected profile. Another physical unit of the same model may have a different serial number and therefore a different identity. Extension treats it as a new display without copying another unit's calibration. On laptops, the daemon also reads lid state. UPower is optional, but recommended: with UPower available, lid changes arrive as D-Bus events and the daemon can react immediately. Without UPower, the daemon falls back to polling `/proc/acpi/button/lid/*/state` at `--lid-poll-interval`, which defaults to `1s` and is not available on every system. If neither source exists, lid-aware switching is disabled and monitor hotplug still works. Lid state is not a separate profile type. Save the profile for the monitor setup you actually have attached. When the lid is closed and an external output has an awake, nonzero mode and remains enabled in the target profile, hyprmoncfg treats internal laptop-panel outputs like `eDP-1`, `LVDS-1`, or `DSI-1` as forced off for that apply. Modeless, disabled, sleeping, and synthetic fallback outputs do not qualify. Saved profiles are not rewritten. If workspace rules target the forced-off internal panel, those workspaces are moved to the first enabled external output in the selected profile. The built-in panel stays off only while an external display actually shows a picture. When every external the profile keeps on is modeless, asleep, or missing, and a connected built-in panel would be off, whether because the lid is closed or because the profile turns it off, the daemon turns the panel on, to the right of the other displays. It logs `no external display shows a picture` when it does. If the reload turns the panel on without a mode, as i915 does with the lid closed, the daemon sets the panel's mode directly, and the apply only counts once the panel has one. Some drivers only give a modeless external its mode back once another output is lit, so without this a clamshell setup could stay dark until the lid is opened. Once an external has a mode, the next pass applies the profile as saved and the panel goes off again. While nothing is lit, a missing mode also doesn't count toward stepping the external's settings down. > **Remove Throwaway Profiles** > > The daemon does not know which profiles are “real” and which were temporary experiments. Any profile with a positive hardware match can be eligible. An old throwaway profile with a high enough score can win over the one you actually want. If you want reliable auto-switching: - Save profiles for every real monitor setup you want the daemon to handle - Keep one profile per setup -- don't accumulate near-duplicates - Delete experimental profiles when you're done experimenting - If two profiles tie, the one whose name comes first alphabetically wins - When auto-switching picks the wrong profile, start by listing the files in `~/.config/hyprmoncfg/profiles/` -- a forgotten profile is almost always the answer ## Run manually For testing or one-off use: ```bash hyprmoncfgd ``` ### Useful flags ```bash hyprmoncfgd --hotplug-debounce 1s # wait longer before applying after a plug event (default 300ms) hyprmoncfgd --debounce 1500ms # wait longer on every other trigger, and on hotplug too unless set above hyprmoncfgd --wake-settle 2s # quiet period after displays wake hyprmoncfgd --poll-interval 5s # how often to run fallback monitor checks hyprmoncfgd --lid-poll-interval 1s # how often to run fallback lid checks hyprmoncfgd --profile desk # always apply this specific profile hyprmoncfgd --quiet # suppress log output ``` ## Forcing a specific profile Use `--profile ` to bypass automatic matching entirely. The daemon applies this one profile every time, regardless of what's connected. This is useful when you know exactly which setup you're on and want to eliminate any chance of a wrong match. Stop the running daemon first, then start it with the flag: ```bash systemctl --user stop hyprmoncfgd hyprmoncfgd --profile conference-projector ``` The daemon owns a per-session writer lock. If a direct editor or another daemon already owns it, a starting daemon logs the contention and waits without changing monitor configuration or repeatedly exiting under systemd. Close the direct editor to let the daemon start serving IPC. Stopping the service also cancels the wait. Direct writers still use the lock rather than racing another writer. Starting with monitor management off preserves the handoff: it does not restore the generated include. Read-only dialect discovery still runs, so a later wake uses the correct Lua or legacy syntax even if Hyprland is temporarily too busy to report its version. Use `hyprmoncfg manage` to opt back in. ## Logs ```bash journalctl --user -u hyprmoncfgd -f ``` The log shows every step: which profiles were scored, what each one scored, which one won, what generated monitor config was written, and whether verification passed. This is the first place to look when you want to understand why the daemon picked a particular profile. Raw monitor-event arrival, slow or failed compositor queries, and reconciliation duration are logged separately. Compare these timestamps to distinguish time spent before an event arrives from time spent querying or applying a profile. Query timing messages include the operation and elapsed time without adding monitor serial numbers. > **Separate Matching From Applying** > > If you’re not sure whether the daemon picked the wrong profile or failed to apply the right one, test the profile directly with `hyprmoncfg apply `. If the layout looks correct, the problem is matching, not applying – check the logs and your profile directory. > **Filing A Matching Bug** > > If you think the daemon selected the wrong profile, [open an issue](https://github.com/crmne/hyprmoncfg/issues/new) and include **all** profiles from `~/.config/hyprmoncfg/profiles/`, not just the one you expected to win. Matching depends on the full candidate set. --- # Omarchy Quattro Panel Canonical URL: https://hyprmoncfg.dev/omarchy/ ## Displays, handled The [hyprmoncfg: Multi-Monitor Manager for Omarchy](https://github.com/crmne/omarchy-hyprmoncfg) plugin is a native graphical panel for Omarchy Quattro. Arrange displays visually, plan workspaces, and save hardware-aware profiles that switch automatically on hotplug and lid events. Open it from the bar to see the live layout, the matching profile, and whether hyprmoncfg is managing your displays. hyprmoncfg is a separate project from [HyprMon](https://github.com/erans/hyprmon), the terminal monitor tool linked in Omarchy's manual. ![hyprmoncfg panel for Omarchy Quattro](https://raw.githubusercontent.com/crmne/omarchy-hyprmoncfg/main/preview.png) If you find the panel useful, I'd appreciate a [star on GitHub](https://github.com/crmne/omarchy-hyprmoncfg). It helps get the word out. Choose **Expand** to open the graphical editor inside the panel. Its **Layout**, **Workspaces**, and **Profiles** pages let you configure the setup without opening a terminal. The optional **TUI** button opens the companion terminal editor, which is also useful from a TTY or over SSH when you need to work on a running Hyprland session without its graphical panel. Turn management on and hyprmoncfg switches profiles automatically on monitor hotplug and laptop lid events. Turn it off to hand display management back to Omarchy. Monitor ownership and workspace ownership are separate; see the compatibility notes below. ## Install the panel Get it from the [Omarchy Plugins marketplace](https://plugins.omarchy.org/plugin.html?id=crmne.hyprmoncfg), or install it directly: ```bash omarchy plugin add https://github.com/crmne/omarchy-hyprmoncfg.git --enable ``` If hyprmoncfg is already installed, the panel connects to its daemon over the local IPC socket and updates as monitor state changes. If it is missing, open the panel and choose **Install hyprmoncfg**. The panel uses Omarchy's normal presented package flow to install the stable AUR package and enables and starts `hyprmoncfgd.service`. The current installer opens the companion TUI after installation. You can use it for initial setup or return to the panel and choose **Expand** to arrange and save your first layout graphically. The panel refreshes as soon as the daemon is ready. ## What the panel controls - **Managed by hyprmoncfg** enables or disables the user daemon - **Expand** opens the native graphical editor - **Layout** provides drag-and-drop arrangement with snapping, resolution, refresh rate, scale, rotation, mirroring, and colour settings - **Workspaces** provides manual, sequential, or interleaved plans, plus **Off** to leave workspace rules to another manager - **Profiles** manages saved arrangements and automatic selection - **Preview & save** lets you try a layout before confirming and saving it; unconfirmed changes revert automatically after the preview deadline - **TUI** opens the optional terminal editor The panel is a desktop surface for the same daemon and IPC protocol used by the TUI and CLI. It does not maintain another copy of monitor state or write Hyprland configuration on its own. ## When Omarchy still moves your displays Omarchy also changes monitor state from its watcher, clamshell, startup, and wake paths. These can conflict with another monitor manager. hyprmoncfg includes automatic compatibility measures: - hyprmoncfg writes its own `~/.config/hypr/hyprmoncfg-monitors.lua` and adds one line at the end of `hyprland.lua` to load it. This gives its generated rules precedence over earlier configuration during a reload. Scripts that send later monitor commands can still change the live layout - the daemon stops Omarchy's monitor watcher while it owns your displays - each apply shares the internal panel's position and scale through a marked block at the start of an existing `monitors.lua`, because Omarchy's clamshell script reads that file rather than following generated includes. The rest of your file is preserved, and the block is removed when management is handed back. The scale is also recorded in Omarchy's state file The daemon also shares Omarchy's native **Laptop Display** toggle. When a profile disables the internal display while an external display is active, it records that choice in Omarchy's manual-disable flag before reloading. Omarchy's wake and clamshell paths already respect this flag, so they leave the disabled panel alone instead of repeatedly enabling it on the lock screen. Changing **Hardware → Laptop Display** or its keybinding updates the active profile's internal-display setting. The daemon uses the saved profile as its base, preserving the display's position, scale, and mode when turning it back on. If an older external-only profile omits the laptop display entirely, enabling it adds the panel to the right of the existing layout, using its reported mode or an advertised mode when the disabled panel has no live geometry. The change is saved after a successful apply and keeps automatic profile selection in its current mode. A toggle can take up to the daemon's polling and debounce interval to appear. Preview rollback restores the previous native flag as well as the generated configuration. Flag changes during sleep, lid changes, and external-monitor reconnection are treated as recovery activity, not as edits to your saved profile. This integration uses Omarchy's existing user state; it does not modify packaged scripts or require the proposed monitor-management switch. The flag continues to reflect the last applied layout when management is handed back. Other tools can still send conflicting monitor commands directly, and future Omarchy changes may require adapting this integration. ### Omarchy 4.5 per-monitor workspaces Omarchy 4.5 release candidates introduce separate workspace slots 1 through 10 on each monitor. Number-key bindings and bar labels use those local slots, while Hyprland still uses global workspace IDs underneath. Omarchy also moves and renumbers workspaces to keep them in each monitor's block. This can conflict with a hyprmoncfg profile that assigns global workspaces across displays, such as 1–3 on one screen and 4–6 on another. The monitor compatibility measures in hyprmoncfg 1.25.1 and earlier do not disable Omarchy's workspace manager. Loading workspace rules last is not sufficient to prevent later reconciliation from changing them. If you want Omarchy to own workspace placement, choose **Off** for the profile's workspace strategy. hyprmoncfg then writes no workspace rules for that profile and retains its saved plan for later use. This does not restore global number-key behaviour or undo workspace IDs Omarchy has already changed. Keeping global workspace assignments requires Omarchy's per-monitor behaviour to stand down as well. The proposed [per-monitor workspace toggle](https://github.com/omacom/omarchy/pull/16213) is tracked upstream; it is not part of Omarchy 4.5.0rc2. hyprmoncfg 1.26.0 and newer make an enabled workspace planner own global numbering once its plan places a numbered workspace. A plan of only named or special workspaces, such as `special:qconsole`, leaves Omarchy's per-monitor workspaces and shortcuts alone. The existing generated Lua file disables Omarchy's workspace reassignment and restores global shortcuts, without another include or changes to packaged Omarchy files. This applies through the shared engine used by the daemon, TUI and panel. **Off** continues to delegate workspace management. Pair global mode with the optional [Global Workspaces widget](https://github.com/crmne/omarchy-global-workspaces). It displays the real workspace IDs and highlights the globally focused workspace on every bar, matching Omarchy's original widget. Omarchy's stock RC2 widget still assumes per-monitor numbering. Switching ownership does not automatically move or renumber existing windows. ### Check the configuration load order Check the load order at any time: ```bash hyprmoncfg doctor ``` If your Hyprland config is managed by a dotfile tool such as chezmoi or stow, keep the line `hyprmoncfg doctor` prints in your source copy. Otherwise your dotfile tool and hyprmoncfg will keep re-adding and removing it. ## Remove it ```bash omarchy plugin remove crmne.hyprmoncfg ``` Removing the panel leaves hyprmoncfg and your saved profiles installed. Turn off **Managed by hyprmoncfg** first if you also want Omarchy to resume display management. --- # Dotfiles Integration Canonical URL: https://hyprmoncfg.dev/dotfiles/ ## The idea You have a desktop, a laptop, maybe a Raspberry Pi. Each one connects to different monitors. But your preferred layouts -- the positions, scales, workspace assignments -- those are yours. They should travel with you. hyprmoncfg stores profiles in `~/.config/hyprmoncfg/profiles/`. Each profile has a canonical JSON file plus generated `.conf` and `.lua` sidecars. Add this directory to your dotfile manager and every machine gets your full profile library. The daemon on each machine looks at what's actually plugged in and picks the right profile. Your desktop applies "desk". Your laptop at a conference applies "projector". Your Raspberry Pi applies "tv". Same dotfiles, different hardware, correct layout every time. ## What to commit (and what not to) **Commit**: `~/.config/hyprmoncfg/` -- your profile library. **Don't commit**: the generated `~/.config/hypr/hyprmoncfg-monitors.conf` or `~/.config/hypr/hyprmoncfg-monitors.lua` -- hyprmoncfg rewrites it from the selected JSON profile and current monitor state. Committing it causes conflicts between machines with different monitors. **Do commit**: the one line hyprmoncfg adds at the end of your Hyprland config to load that file. It names no machine-specific path, so it works everywhere, and committing it stops your dotfile tool and hyprmoncfg from taking turns undoing each other. ## chezmoi Add the config directory: ```bash chezmoi add ~/.config/hyprmoncfg ``` That's it. Your profiles are now versioned and will be deployed to every machine where you run `chezmoi apply`. When you save a new profile or update an existing one, tell chezmoi to pick up the changes: ```bash chezmoi re-add ~/.config/hyprmoncfg ``` (`re-add` updates files that chezmoi already tracks. You only need `add` for the initial setup.) ## Other dotfile managers The same principle applies to any dotfile manager. The directory to track is: ``` ~/.config/hyprmoncfg/ ``` With GNU Stow, symlink the directory from your dotfiles repo. With yadm, just `yadm add ~/.config/hyprmoncfg`. With bare git repos, add the path to your tracking. ## A practical example Say you speak at conferences. At home, you have a desk with an external monitor. On the road, you plug into whatever projector the venue provides. 1. At home, open the TUI, arrange your desk layout, save as `desk` 2. At a conference, plug into the projector, open the TUI, arrange, save as `conference-1080p` 3. At another venue with a 4K projector, save as `conference-4k` 4. Run `chezmoi re-add ~/.config/hyprmoncfg` after each new profile Now the daemon handles it. Arrive at the venue, plug in, and the right profile is applied before you've even opened your slides. When you get home, dock the laptop, and your desk layout comes back instantly. No manual config editing. No remembering which `monitor=` lines go where. Just plug in and go. --- # Virtual Desktops Canonical URL: https://hyprmoncfg.dev/virtual-desktops/ ## The problem with Hyprland workspaces You have three monitors. You press `SUPER+2` and exactly one of them changes, because in Hyprland a workspace belongs to a single monitor. That gets in the way when you want scenes. Work is a browser, an editor, and logs across all three screens. Music is something else entirely. You want one keypress to swap the whole set, not three keypresses to swap them one at a time. GNOME and KDE work that way; Hyprland does not. hyprmoncfg follows Hyprland here. Its workspace planner decides which workspaces live on which display, and stops there -- it will not pretend the compositor has a concept it does not have. ## Use hyprland-virtual-desktops [hyprland-virtual-desktops](https://github.com/levnikmyskin/hyprland-virtual-desktops) adds scenes properly. It is a Hyprland plugin, a real `.so` loaded into the compositor, so it changes how workspaces work rather than driving them from outside. ```bash hyprctl dispatch vdesk 2 # every monitor moves together hyprctl dispatch movetodesk 3 # send a window to another desk hyprctl dispatch nextdesk ``` ## Turn the workspace planner off hyprmoncfg's planner writes `workspace_rule` entries pinning workspace 1 to this monitor and workspace 2 to that one. virtual-desktops assigns workspaces to monitors itself, differently per desk. Leave both on and whichever ran last wins. So set **Strategy** to Off in the Workspaces tab, on every profile you use with the plugin. hyprmoncfg then writes no workspace rules at all, and the split is clean: hyprmoncfg puts the monitors where they belong, virtual-desktops decides what appears on them. You lose nothing. Spreading workspaces across displays is what the plugin does, and it does it per desk rather than once. ## What happens when you dock hyprmoncfg matches the docked profile, applies the mode, scale, rotation and position for each display, reloads Hyprland, and stops. It does not touch workspaces. virtual-desktops takes it from there. It notices the monitor set changed and restores which workspace each monitor was showing, using `plugin:virtual-desktops:rememberlayout`. Set that to `monitors` rather than `size` -- it keys on monitor identity, which is what hyprmoncfg matches profiles on, so the two agree about what counts as the same setup. If the plugin needs a nudge afterwards, every profile has an **Exec** field that runs once the layout is applied and Hyprland has reloaded. Point it at a script: ```bash #!/usr/bin/env bash hyprctl dispatch vdeskreset hyprctl dispatch vdesk 1 ``` The command runs directly rather than through a shell, so a `&&` or a pipeline belongs in the script, not in the field. ## A practical example 1. Open the TUI, arrange your docked layout, save it as `desk` 2. Undock, arrange the laptop on its own, save that as `mobile` 3. Set **Strategy** to Off on both, in the Workspaces tab 4. Set `plugin:virtual-desktops:rememberlayout = monitors` in your Hyprland config Dock the laptop and hyprmoncfg puts the monitors back where they belong. Press `SUPER+2` and all of them move together. --- # 2-in-1s and Tablets Canonical URL: https://hyprmoncfg.dev/two-in-one/ ## Automatic rotation On a 2-in-1 laptop or a tablet, hyprmoncfg can turn the built-in panel with the device. It reads the accelerometer through iio-sensor-proxy, so there is no script to write and nothing fights over the rotation: - The panel turns within a moment of the device settling. - Monitors beside it move to stay touching, the way they do when you change a display's resolution. - The touchscreen and pen turn with the panel. - Every Hyprland reload keeps the current rotation, because the generated config always holds it. Your saved profile never changes. It keeps describing the layout with the device upright, and the rotation is applied on top while hyprmoncfgd runs. ## Setting it up 1. Install iio-sensor-proxy, which provides the accelerometer: ```bash sudo pacman -S iio-sensor-proxy ``` 2. Make sure your user can read the tablet-mode switch, so a convertible only turns when folded into a tablet. Omarchy users are in the `input` group already; check with `id`, and add yourself with `sudo usermod -aG input $USER` if not. 3. In the TUI or the Omarchy panel, select the built-in panel and set **Rotation** to **Auto**. Save the profile. 4. Remove any script of your own that rotates the screen, such as one built on `monitor-sensor` or `iio-hyprland`. Two programs rotating the same panel will undo each other. **Auto** appears only for a built-in panel, and only when hyprmoncfgd reports an orientation sensor. Restart hyprmoncfgd after installing iio-sensor-proxy. iio-sensor-proxy only lets the active session claim the sensor, and a daemon started at login can ask before the login screen has let go of the seat. The daemon keeps asking, every 2 seconds at first and then up to once a minute, and `hyprmoncfg rotation` says it is waiting. Auto starts working without a restart. ## Upright The rotation the panel has when you choose **Auto** is its upright rotation. For most devices that is **Normal**. Some tablets have a panel mounted in portrait: set the rotation that looks right with the device upright first, then choose **Auto**. The inspector then shows, for example, **Auto, upright 270°**, and the sensor's turns add to that. Choosing **Auto** also takes the device's current position as upright, as **Calibrate** does, so the panel keeps the rotation it had. Hold the device the way that rotation looks right when you choose it. Normal back to **Auto** restores the remembered upright rotation instead and leaves the calibration alone. Without a sensor reading, for example while the device lies flat, or during a preview, the calibration stays as it was. Leaving Auto remembers that upright rotation. Choosing **Normal** and then **Auto** again restores it, because Normal says nothing about which way is up. To replace it, choose the new rotation and then **Auto**. To make Normal the upright rotation again, choose any other fixed rotation, then **Normal**, then **Auto**. To hold a turn for a while, use the lock rather than a fixed rotation. ### Calibrate the sensor's upright position If Auto adds a quarter turn even though you selected the correct fixed rotation, hold the device upright relative to its keyboard (or the way you normally use a tablet), then press **Calibrate** in the Omarchy panel, press `C` in the TUI, or run: ```bash hyprmoncfg rotation calibrate ``` This records the sensor reading as upright and unlocks rotation. It leaves saved profiles unchanged and persists across daemon restarts. Set the panel's correct fixed rotation, such as 270°, before choosing Auto. Direction reversal changes which way turns go; calibration changes where they start. Recalibrate after changing the system sensor mount matrix. Calibration requires a current daemon and refuses to run during a preview or while the sensor reports the device flat. ### Preview behavior A preview applies the orientation at its start and holds it while you decide. Auto rotation resumes after **Keep**, including when keeping a temporary layout without saving a profile. This prevents sensor changes from moving the confirmation controls or racing rollback. ## Tablet mode A convertible with a tablet-mode switch turns its panel only while folded into a tablet, as GNOME does, so a laptop tilted on your lap stays put. Folded back into a laptop, the panel goes upright. A device with no such switch, such as a tablet or a detachable, always follows the sensor. Lying flat keeps the last rotation. ## Rotation lock Lock the rotation to keep the panel as it is, for example to read lying down: ```bash hyprmoncfg rotation lock # hold the current rotation hyprmoncfg rotation unlock # follow the device again hyprmoncfg rotation toggle # switch between the two hyprmoncfg rotation # show the current state ``` Bind `hyprmoncfg rotation toggle` to a key for a one-press lock. On Omarchy, add it to `~/.config/hypr/bindings.lua`: ```lua o.bind("SUPER + O", "Rotation lock", "hyprmoncfg rotation toggle") ``` Elsewhere, bind it the way your config runs any other command. In the TUI, press `L`. In the Omarchy panel, use the lock beside **Auto**. The lock is remembered across restarts. Unlocking turns the panel to the way the device is held now. ## If it turns the wrong way If the panel turns the opposite way to the device, reverse the direction: ```bash hyprmoncfg rotation direction reversed ``` Undo it with `hyprmoncfg rotation direction normal`. The setting belongs to the device, not to a profile, and survives restarts. If the panel is the right way round only when the device is turned, set its upright rotation instead (see [Upright](#upright)). If the sensor reports a non-normal orientation while you hold the device upright, calibrate it as described above. Both come from the device's accelerometer mount matrix in the system hardware database, which is missing or wrong for some models, and GNOME and KDE turn those wrong too. To fix it for every program at once, add an `ACCEL_MOUNT_MATRIX` entry for your device to `/etc/udev/hwdb.d/61-sensor-local.hwdb`, as the [iio-sensor-proxy documentation](https://gitlab.freedesktop.org/hadess/iio-sensor-proxy/) explains, and consider sending it upstream to systemd. Then set the direction back to normal. ## Limits - Fixed rotations of a connected, enabled built-in panel also keep touch and pen aligned, including after disabling Auto or restarting Hyprland. - Touch and pen rotation use Hyprland's global `input:touchdevice:transform` and `input:tablet:transform`. An external drawing tablet turns with the panel too. - Only built-in panels rotate. External monitors don't turn with the device. - Rotation needs hyprmoncfgd. Applying a profile from the TUI or CLI without the daemon uses the upright layout. --- # Commands and Flags Canonical URL: https://hyprmoncfg.dev/commands/ ## `hyprmoncfg` Running `hyprmoncfg` with no arguments opens the TUI. ### Commands | Command | Description | |---------|-------------| | `hyprmoncfg` | Open the TUI | | `hyprmoncfg tui` | Open the TUI (explicit) | | `hyprmoncfg monitors` | List connected monitors with hardware details | | `hyprmoncfg profiles` | List saved profiles | | `hyprmoncfg status` | Show the active profile, daemon state, and connected displays, naming any enabled display without a usable mode and any the daemon runs below its saved settings | | `hyprmoncfg status --json` | Print the stable status schema as JSON | | `hyprmoncfg save ` | Save current monitor state as a named profile | | `hyprmoncfg apply ` | Apply a saved profile | | `hyprmoncfg delete ` | Delete a saved profile | | `hyprmoncfg rename ` | Rename a saved profile and its generated files. Fails if `` is taken, during a preview, or for the profile `hyprmoncfgd --profile` is forced to. Applies nothing and runs no post-apply command | | `hyprmoncfg rotation` | Show automatic rotation of built-in panels: following the sensor, paused while folded as a laptop, or locked | | `hyprmoncfg rotation lock\|unlock\|toggle` | Hold the current rotation, follow the device again, or switch between the two. Needs hyprmoncfgd | | `hyprmoncfg rotation calibrate` | Treat the current sensor reading as upright and unlock rotation. Hold the device upright first; requires daemon calibration support and no active preview. Also `C` in the TUI | | `hyprmoncfg rotation direction normal\|reversed` | Turn panels the other way, for a device whose sensor reports the opposite direction. Needs hyprmoncfgd | | `hyprmoncfg doctor` | Check that Hyprland loads hyprmoncfg's monitor config last | | `hyprmoncfg doctor --fix` | Add or move that include to the end of the Hyprland config | | `hyprmoncfg version` | Print build metadata | ### Common flags | Flag | Description | |------|-------------| | `--config-dir ` | Override the profile storage directory (default: `~/.config/hyprmoncfg`) | | `--monitors-conf ` | Override `HYPRMONCFG_MONITORS_CONF` and the default generated monitor config path | | `--hypr-config ` | Override `HYPRLAND_CONFIG` and the default root config path (`.conf` or `.lua`) | ### Environment variables Both `hyprmoncfg` and `hyprmoncfgd` use these variables when the corresponding flag is not provided: | Variable | Description | |----------|-------------| | `HYPRMONCFG_MONITORS_CONF` | Generated monitor config path to write and reload | | `HYPRLAND_CONFIG` | Hyprland root config path used for include verification | ### Apply flags | Flag | Description | |------|-------------| | `--confirm-timeout ` | Seconds to wait for confirmation before reverting (default: 30) | | `--confirm-timeout 0` | Disable the revert timer entirely | ## `hyprmoncfgd` The daemon. Runs in the foreground by default. ### Commands | Command | Description | |---------|-------------| | `hyprmoncfgd` | Start the daemon | | `hyprmoncfgd version` | Print build metadata | ### Daemon flags | Flag | Description | |------|-------------| | `--config-dir ` | Override the profile storage directory | | `--monitors-conf ` | Override `HYPRMONCFG_MONITORS_CONF` and the default generated monitor config path | | `--hypr-config ` | Override `HYPRLAND_CONFIG` and the default root config path (`.conf` or `.lua`) | | `--profile ` | Force a specific profile instead of auto-matching | | `--debounce ` | Delay before applying after a monitor or lid event (default: 1200ms) | | `--wake-settle ` | Quiet period after displays wake before reconciling monitor changes (default: 2s) | | `--poll-interval ` | Polling frequency for monitor fallback checks (default: 5s) | | `--lid-poll-interval ` | Polling frequency for lid-state fallback checks (default: 1s) | | `--quiet` | Suppress log output | ## Automatic reconciliation Automatic matching preserves a complete saved layout already on screen before falling back to hardware scores. It keeps that choice until the hardware or lid changes. After applying, it tracks the requested configuration and its resolved state: VRR activity, equivalent buffer formats, and rounded scale readbacks do not cause another reload. Changes to the saved configuration (including config-only settings), layout, or workspace rules still require reconciliation. These checks do not extend the wake delay. When a reconciliation would write a generated config identical to the one on disk, the displays already match the profile, and neither the root include nor Omarchy's laptop display flag changes, hyprmoncfg skips the write and the Hyprland reload. Workspace placement and the Post-apply command still run. A lock screen waking with the displays then is not held up by a reload, and binds added at runtime survive it. ## Exit behavior - CLI commands exit non-zero on Hyprland query failures, invalid layouts, missing profiles, or generated-config verification failures. - Legacy include-chain failures are reported before writing. For Lua configs, `apply` reloads Hyprland and asks the active Lua state to confirm that the generated monitor file actually ran. It restores the previous file if it did not. - The daemon exits cleanly on `SIGINT` or `SIGTERM`. - Only one monitor writer can run per user session. If the daemon owns the writer lock, the TUI and mutating CLI commands use its IPC socket automatically. --- # Configuration Files Canonical URL: https://hyprmoncfg.dev/configuration-files/ ## Profile storage Canonical profile JSON files live in: ``` ~/.config/hyprmoncfg/profiles/*.json ``` Each profile has a canonical JSON file. The filename is a simplified version of the profile name -- spaces become hyphens, special characters are dropped. For example, a profile named "Home Office" becomes `home-office.json`. hyprmoncfg also writes generated `home-office.conf` and `home-office.lua` sidecars next to the JSON file. These are fallback exports for people who want to stop using hyprmoncfg but keep the saved layouts as Hyprland config snippets. The JSON remains the source of truth used by hyprmoncfg and `hyprmoncfgd`. `hyprmoncfgd` also keeps `~/.config/hyprmoncfg/display-fallbacks.json` for displays that need a gentle wake or run below their saved settings because they would not stay on at them (see [the daemon guide](/daemon/#displays-that-wont-stay-on)). It is live state, not a profile. Applying any profile clears the stepped-down settings; deleting the file forgets everything once the daemon restarts. > **Every Profile File Is A Match Candidate** > > `hyprmoncfgd` scans every `*.json` file in this directory. Old backups, temporary experiments, and duplicate layouts are not ignored just because you forgot about them. Override the storage directory with `--config-dir`: ```bash hyprmoncfg --config-dir /path/to/profiles hyprmoncfgd --config-dir /path/to/profiles ``` ### What's in a profile Each profile stores: - **Monitor outputs**: hardware identity (make, model, serial), resolution, refresh rate, scale, position, transform, VRR mode (`-1` follows the global `misc:vrr`, `0` off, `1` on, `2` fullscreen only, `3` fullscreen games and video), and `rotation_auto` for a built-in panel that turns with the device, whose `transform` is then its upright rotation - **Workspace settings**: strategy, max workspaces, group size, monitor order, explicit rules Generated workspace plans support `workspaces.persist_all: true` to keep every assigned workspace persistent. Omitted or false retains the first-workspace-per- display default. Each display still has only one default workspace. Manual plans use each rule's `persistent` flag instead. Both editors expose this as Persistence on the Workspaces page; no edits to generated files are needed. On Omarchy, **Move workspace to … monitor** (Super+Shift+Alt+arrow) also moves a persistent planned workspace, pinning it to its new monitor for the rest of the session. It does not change the saved profile: the next reload of the generated file, for example a profile switch, puts the workspace back where the plan says. Monitors are identified by hardware key (`make|model|serial`), not connector name. This means your profiles survive connector swaps between boots. ### Commands after applying a profile The profile's **Exec** field runs a command after Hyprland has applied the layout, and after confirmation for an interactive preview. It receives `HYPRLAND_INSTANCE_SIGNATURE` for the compositor that applied the profile, even when the daemon started without a session environment. Put multiple commands in an executable script and point Exec at that script. For commands which also need the graphical session's environment, ask Hyprland to launch them. For example, on Lua-based Hyprland, this Exec value selects the TV as XWayland's primary output: ```text hyprctl dispatch 'hl.dsp.exec_cmd("xrandr --output HDMI-A-1 --primary")' ``` On legacy Hyprland, use `hyprctl dispatch exec 'xrandr --output HDMI-A-1 --primary'`. Install `xrandr` and replace `HDMI-A-1` with the output you want from `xrandr --query`. Choose it explicitly for each relevant profile; the leftmost, largest, or first output is not necessarily the one you want to game on. The recipe uses a connector name, so update it if you move the cable to another port. It affects XWayland applications which consult the primary flag, not native Wayland window placement. Some applications need to be restarted. Hyprland supplies `DISPLAY` to the launched command. Its dispatch acknowledges the launch, not the eventual `xrandr` result; run the command in a terminal first to check the output name. This avoids scanning X sockets, and leaves the profile schema and existing Exec editor unchanged. ## Profile hygiene If you want predictable daemon behavior, keep this directory curated: - Create profiles for every real monitor scenario you expect auto-switching to cover - Keep one profile per real monitor setup you actually want auto-applied - Delete stale profiles instead of renaming them and leaving them in place - Store backups somewhere else if you do not want them considered during matching - Re-save a profile after major hardware changes instead of accumulating near-duplicates ## Hyprland targets hyprmoncfg writes a file it creates and owns, so it never has to overwrite a config you or your distribution wrote. Default legacy apply target: ``` ~/.config/hypr/hyprmoncfg-monitors.conf ``` Default legacy root config used for source verification: ``` ~/.config/hypr/hyprland.conf ``` On Hyprland 0.55+, if `~/.config/hypr/hyprland.lua` exists, hyprmoncfg switches to Lua mode and uses: ``` ~/.config/hypr/hyprmoncfg-monitors.lua ~/.config/hypr/hyprland.lua ``` If Hyprland 0.55+ is still using `hyprland.conf`, hyprmoncfg stays in legacy mode. When `HYPRLAND_CONFIG` is set, hyprmoncfg uses it as the root config path. An explicit `--hypr-config` takes precedence, and paths ending in `.conf` or `.lua` force the matching format. Override either path: ```bash hyprmoncfg --monitors-conf /path/to/monitors.conf --hypr-config /path/to/hyprland.conf hyprmoncfgd --monitors-conf /path/to/monitors.conf --hypr-config /path/to/hyprland.conf hyprmoncfg --monitors-conf /path/to/monitors.lua --hypr-config /path/to/hyprland.lua hyprmoncfgd --monitors-conf /path/to/monitors.lua --hypr-config /path/to/hyprland.lua ``` To configure both binaries once, set the equivalent environment variables: ```bash export HYPRMONCFG_MONITORS_CONF=/path/to/monitors.conf export HYPRLAND_CONFIG=/path/to/hyprland.conf ``` Explicit flags take precedence. A systemd-managed daemon must receive these variables through the user manager's environment; restart `hyprmoncfgd` after changing them. ## The include-chain check hyprmoncfg confirms that Hyprland loads the generated monitor file. This catches a surprisingly common problem: a tool writes a config file that Hyprland never reads, so nothing happens and you're left wondering why. hyprmoncfg adds the include itself, at the end of your root config, and moves it back to the end if something is appended after it. Loading last is what makes the applied layout final: any monitor rule read afterwards would override it. `hyprmoncfg doctor` reports the current state and `--fix` settles it on demand. Saved profiles are authoritative for the connected monitor set. When a connected output is absent from the selected profile, the generated file writes an explicit disabled rule for it. This overrides an earlier wildcard such as Omarchy's preferred/automatic monitor default instead of letting that default leave an unwanted display enabled. The generated file also keeps the rule for an enabled display in the selected profile that is currently disconnected or powered off, addressed by its hardware description. When that display comes back, Hyprland sets its saved mode straight away instead of starting it in a default mode that the next apply then changes. Some displays take several seconds to wake, and a second mode change during that time can knock them off the link again, over and over. Displays that can only be addressed by connector name (duplicate models, a description another connected display shares, or one Hyprland's legacy syntax cannot express), mirrors, and built-in panels are left out, so a rule never lands on a different display plugged into the same port. Workspace rules still only target connected displays. The Lua include resolves its own path at load time: ```lua dofile((os.getenv("XDG_CONFIG_HOME") or (os.getenv("HOME") .. "/.config")) .. "/hypr/hyprmoncfg-monitors.lua") ``` so the same config works under a different user, a different home, or a dotfile repo shared between machines. Legacy configs get `source = ~/.config/hypr/hyprmoncfg-monitors.conf`. If your Hyprland config is managed by a dotfile tool, keep that line in your source copy so the two do not keep undoing each other. For Lua configs, hyprmoncfg reloads Hyprland and asks the active Lua state to confirm that the generated monitor file actually ran. If it did not, hyprmoncfg restores the previous file (or removes a newly created one) and reloads again. This works with `require`, `pcall`, `dofile`, custom `package.path` values, and computed include paths because Hyprland loads the real config itself. If your files live elsewhere, point hyprmoncfg at them with `--monitors-conf` and `--hypr-config`; it will add an include for whatever target you name. Upgrading from a version that wrote `monitors.conf` or `monitors.lua` needs nothing from you. On the next apply, hyprmoncfg writes its own file, adds the include, and replaces the body of the file it used to generate with a note saying where the rules moved. A `monitors.conf` or `monitors.lua` that hyprmoncfg did not generate is never touched. ## What gets written When you apply a profile (via TUI, CLI, or daemon), hyprmoncfg writes the active generated monitor file. Legacy configs get `hyprmoncfg-monitors.conf` with either `monitorv2 { }` blocks (Hyprland 0.50+) or legacy `monitor = ` lines, depending on your Hyprland version. Lua configs get `hyprmoncfg-monitors.lua` with `hl.monitor({ ... })` and `hl.workspace_rule({ ... })` calls. Every monitor rule states its VRR mode, including `vrr = 0` for off, because Hyprland otherwise falls back to its global `misc:vrr` setting and a profile set to off could still get VRR. hyprmoncfg marks generated files with `Generated by hyprmoncfg` on the first line. It fully manages and rewrites a missing target or a target carrying that marker. An existing file without the marker is treated as user-owned. The TUI and interactive CLI ask before replacing it; the daemon and non-interactive CLI refuse to replace it. To preserve a hand-written `monitors.conf` or `monitors.lua`, select a separate generated target such as `hyprmoncfg-monitors.conf` or `hyprmoncfg-monitors.lua` with `--monitors-conf` (or `HYPRMONCFG_MONITORS_CONF`) and include that file from the Hyprland root config. Per-profile `*.conf` and `*.lua` files in `~/.config/hyprmoncfg/profiles/` are different: they are exported copies of each saved profile. Applying a profile still regenerates the active target from JSON and the current monitor state so lid handling, duplicate monitor resolution, Hyprland version detection, verification, and rollback keep working. When a connected built-in panel rotates automatically, the file also sets `input:touchdevice:transform` and `input:tablet:transform` to the panel's current rotation, so the touchscreen and pen turn with it. hyprmoncfg 1.26.0 and newer also include an Omarchy workspace handoff when the workspace planner is enabled and places at least one numbered workspace. In the same generated Lua file, it disables Omarchy's per-monitor reassignment and restores global number, move, history, and cycling shortcuts. There is no additional include. The block detects Omarchy's workspace module at runtime and does nothing on plain Hyprland or older Omarchy installations without that module. Planner **Off**, or a plan of only named or special workspaces, omits it, so the next reload restores the distribution's workspace behaviour. Use a global workspace bar widget with this mode; Omarchy 4.5 RC2's stock widget still labels workspaces per monitor. Existing windows retain their IDs until explicitly moved. The generated Lua file also sets `omarchy_monitor_panel_settings = false`, so settings saved in Omarchy's display panel do not override your profile when a monitor is plugged in or Hyprland starts. Edits made in that panel are not lost: while hyprmoncfg manages your monitors, the daemon folds them into the active profile. On Omarchy it also sets `GDK_SCALE` from the lowest active scale and honours Omarchy's Mirror Display toggle while it is on. `GDK_SCALE` is only written while Hyprland runs with `xwayland:force_zero_scaling` on, which is the state Omarchy's panel scaling sets up: X11 clients then get a 1x screen and scale themselves. With that option off, XWayland gives X11 clients the monitor's own resolution and the compositor scales them, so a global `GDK_SCALE` would be applied a second time and apps that honour it, JavaFX wallets and GTK apps among them, come up magnified on a scaled display. hyprmoncfg leaves the variable alone there, and on an older Hyprland that cannot report the option it keeps writing it as before. When the file sets `GDK_SCALE`, it also runs `dbus-update-activation-environment --systemd GDK_SCALE=` each time Hyprland loads it. Apps started through systemd or D-Bus activation, such as Omarchy's launcher and `uwsm-app`, then get the new value after a profile switch instead of the one exported at login. Running apps keep the scale they started with until they are restarted. Do not put unrelated Hyprland settings in that file. Keep blocks like `render`, `cursor`, `misc`, and `env` in other sourced config files. The file is written atomically (temp file + rename) to prevent partial writes from corrupting your config. Interactive applies keep an in-memory snapshot and restore it on rejection, timeout, interruption, or quit unless you explicitly keep the new configuration. ## Portability Profile JSON files are portable across machines. The daemon uses hardware identity matching to score profiles, so a profile saved on your desktop will work on your laptop if the same monitors are connected. The generated `.conf` and `.lua` sidecars are useful fallback snippets, but JSON is the portable profile format hyprmoncfg reads. Add `~/.config/hyprmoncfg` to your dotfile manager to share profiles across all your machines. See the [dotfiles guide](/dotfiles/) for details. --- # IPC Protocol Canonical URL: https://hyprmoncfg.dev/ipc/ ## Overview `hyprmoncfgd` exposes a newline-delimited JSON protocol on: ```text $XDG_RUNTIME_DIR/hyprmoncfgd.sock ``` The socket is mode `0600`. Protocol version 1 is designed for the bundled TUI and CLI as well as local desktop integrations such as an Omarchy bar panel. When the socket exists, the daemon is the canonical writer. Clients should not edit profiles or the active generated monitor file alongside it. The bundled TUI and CLI fall back to the same core engine only when no daemon owns the session writer lock. ## Envelopes Every message is one JSON object followed by a newline. A request looks like: ```json {"type":"request","protocol_version":1,"id":"1","method":"status"} ``` The matching response repeats the client-generated ID: ```json {"type":"response","protocol_version":1,"id":"1","result":{}} ``` Errors replace `result` with an object containing a stable `code`, a human-readable `message`, and optional `data`. ## Methods | Method | Parameters | Result | |---|---|---| | `status` | none | Status document | | `subscribe` | none | Current status document, followed by `status` events | | `editor_state` | none | Editable live profile, supported modes, and source-profile metadata | | `edit_profile` | full `profile` and one `edit` operation | Updated profile draft | | `scale_info` | `width`, `height` (a mode) and `scale` | Scale row and sharpness for that mode and scale | | `preview` | `profile_name` or a full `profile`; optional `timeout_seconds` and `save_on_commit` | Transaction | | `confirm` | `transaction_id` | none | | `commit` | `transaction_id`; `save` boolean | none | | `revert` | `transaction_id` | none | | `save` | full `profile` | none | | `delete` | `name` | none | | `rename_profile` | `name`, `new_name` | none | | `set_profile_auto` | `enabled` boolean | none | | `set_rotation` | optional `locked`, `reversed`, or `calibrate` booleans | none | `rename_profile` renames a saved profile and its `.conf` and `.lua` files, and the daemon's active, manual and last-applied references follow it. It applies nothing and runs no post-apply command. It keeps `created_at`, updates `updated_at`, and treats names that share a file as the same name, so a change of case works and `Work Desk` cannot become `work-desk` beside an existing `Work Desk`. It fails when the new name's files exist, during an interactive preview, and for the profile the daemon was started with `--profile` on. Daemons with this method report `daemon.rename_supported: true` in the status document. Hide Rename when it is absent: older daemons answer with an unknown-method error. The typed Go client checks this. A transaction contains an opaque `id`, the effective profile, and an RFC 3339 `deadline`. An omitted or nonpositive `timeout_seconds` uses the 30-second default. Explicit durations from older clients are still honored. The deadline starts after apply verification succeeds; the confirmation interval is separate from link readiness. ## Safe preview lifecycle Only one preview can be active at a time. It belongs to the connection that created it. If that connection disappears—for example, because changing the monitor layout rebuilt a screen-bound panel—the preview stays armed until its original deadline. Its transaction metadata remains available as `daemon.preview` in status, and a replacement client can reclaim it by sending the same transaction ID to `confirm`, `commit`, or `revert`. `daemon.preview.reclaimable` is true only after the owning connection disappears. A subscriber must not present a modal confirmation for another live client's preview: observing a transaction ID does not grant ownership. Present controls for transactions created by your connection, or for a reclaimable transaction. Treat a missing `reclaimable` field from an older daemon as false. The daemon's deadline remains authoritative after reclamation, and an expired preview cannot be kept by a late commit. A preview is reverted when any of these happens: - the client calls `revert` - the deadline expires - the daemon shuts down - monitor management is turned off Rollback restores both the generated monitor rules and any root-config include added or moved by that preview. If the root config was edited in the meantime, rollback reports the conflict and preserves the edited config and its target instead of overwriting those edits or creating a dangling include. After `confirm`, the selected profile becomes a session-scoped override for the current connected monitor set. The daemon still owns monitor management, but automatic best-match selection is paused until the hardware set changes, the daemon restarts, or `set_profile_auto` is called with `enabled: true`. A late `confirm` or `revert` returns the `transaction_unavailable` error code. `commit` completes the same safe preview transaction and can atomically save its effective profile before making the layout permanent. If saving fails, the transaction stays armed and still reverts at its deadline. Compact editors should use `save_on_commit: true` when creating a draft preview (or `commit` with `save: true`) for “keep and save” rather than racing separate `confirm` and `save` requests. Keeping that intent in the daemon lets a replacement panel finish the transaction correctly after reconnecting. ## Status events Status includes `workspace_plan`, an array of `{output_key, output_name, workspaces}` groups resolved from the explicit current Hyprland rules using the same hardware identity matching as the editor. Disabled, modeless, synthetic and mirrored outputs have no independent group. This is a read-only view of live rules, not a saved-profile preview or a declaration of workspace ownership. An absent field means an older daemon. An empty array means a known empty plan. Shell clients merge this with their live compositor workspace model: a workspace's actual location always wins over its assignment. Switching a workspace remains a direct compositor action; there is no workspace-switching IPC method. The additive field retains protocol/schema version 1 and existing subscriptions. Monitor summaries add `usable` and `health` (`usable`, `off`, `sleeping`, `no_signal`, or `synthetic`). `enabled` alone is not evidence of a working mode. Older daemons omit these fields; clients must not interpret absence as failure. A monitor summary adds `fallback` when the daemon runs that display below its saved settings because it would not stay on at them. It has a `reason` (`dropping`: it kept disconnecting right after connecting; `no_mode`: it kept coming back without a mode) and `running`, a plain description such as `without VRR` or `at 120 Hz without VRR`. The saved profile is unchanged, and confirming or committing any preview clears every fallback. Absent means the display runs at its saved settings, or the daemon predates the field. A daemon with orientation support adds `rotation` to the status document: `available` (an accelerometer reports the orientation), `orientation` (iio-sensor-proxy's `normal`, `left-up`, `bottom-up`, `right-up` or `undefined`), `quarters` (the counterclockwise quarter turns applied now to built-in panels that rotate automatically), `locked`, `reversed` (the sensor's turns are applied the other way, for a device whose accelerometer reports the opposite direction), and on a convertible `tablet_mode` and `paused` (folded as a laptop, so panels stay upright). Absent `rotation` means the daemon predates it; clients then offer neither automatic rotation nor the lock. `set_rotation` changes only the fields it is given: `locked` holds or releases the current turn, `reversed` sets the direction. Both persist across daemon restarts. `calibrate: true` records the current sensor orientation as upright and unlocks rotation, without editing profiles. It cannot be combined with other rotation edits and fails during an interactive preview or without a valid sensor orientation. Status advertises `calibration_supported: true` and `sensor_upright` (the raw quarter-turn reading used as zero). Clients must check that capability before sending calibration: old servers ignore unknown fields. The typed Go client performs this check. Missing calibration fields retain the original zero baseline. Direction reversal applies after subtracting the sensor baseline. `sensor_claim_pending: true` with `available: false` means iio-sensor-proxy is running but has refused the claim, which polkit does until the session is active. The daemon keeps retrying, so clients should say so rather than suggest installing a sensor service. `rotation_upright` holds a sideways upright rotation while a panel set to Normal is away from Auto; clients leave it alone. A profile output with `rotation_auto: true` turns with the device; its `transform` is the rotation it has when the device is upright. Profiles, drafts, `editor_state` and `edit_profile` always describe that upright layout, and the daemon turns it on apply, including previews, moving attached displays as a resize would. Sensor-driven changes pause until the preview ends. Monitor summaries keep reporting the live transform. Editor `displays` add `rotation_auto_supported`, true only for a built-in panel when a sensor is available; only then may an editor offer the `rotation_auto` edit, which the daemon refuses for any other display. Older clients that don't know the field drop it when they save, so upgrade both clients together. Editor documents list `vrr_modes`, the VRR values `edit_profile` accepts (`-1` follows the global `misc:vrr`, `0` off, `1` on, `2` fullscreen, `3` fullscreen games and video). An editor offers only these; when the field is missing the daemon accepts `0`, `1` and `2`. Editor documents add `workspace_persistence_supported`. Only when true may an editor offer `workspaces.persist_all`. Missing capability means unavailable, not false user intent. The typed client rejects sending this setting to older daemons rather than silently losing it. Older clients retain their existing first-per-display default; upgrade both clients before editing profiles that use the new policy, since old clients cannot preserve an unknown field. After `subscribe`, the daemon pushes a fresh status document whenever monitor or profile state changes: ```json {"type":"event","protocol_version":1,"event":"status","data":{}} ``` The document schema is versioned independently with `schema_version`. `daemon.profile_override` names the session-scoped manual profile for the current monitor set; when it is absent, profile choice is automatic. While an interactive change is awaiting confirmation, `daemon.preview` contains its `transaction_id`, `profile_name`, `deadline`, full effective `profile`, and optional `save_on_commit` intent. The profile lets a screen-bound integration reconstruct the target layout after the monitor change replaces its process or panel. Each profile summary includes `connected_outputs`, `connected_enabled_outputs`, `exact_display_match`, `match_score`, and a `match_reasons` breakdown with the count and score contribution for each connection state. With the lid closed and an external connected, built-in panels appear as `lid_closed_kept_off` (+100 each) or `lid_closed_on` (+50 each) instead of `connected_kept_off` or `connected`. Older clients that don't know a kind should still show its count and points. `exact_display_match` is true when the profile accounts for every connected display and has no saved display missing; a connected display deliberately kept off still counts as part of that setup. Integrations should only offer a profile for manual selection when `connected_enabled_outputs` is greater than zero. This guarantees that applying the profile leaves at least one currently connected output enabled. The two connection counts let a browser distinguish all available saved outputs from the subset the profile enables. Monitor summaries include the connector, make, model, serial, output `key`, hardware `match_key`, active mode, physical and logical dimensions, position, scale, transform, internal/focused flags, and enabled state. Integrations can therefore render the same monitor identity and layout information as the TUI without querying Hyprland separately. `hyprmoncfg status --json` prints the same shape without requiring clients to speak the socket protocol. `editor_state` is intentionally fetched on demand rather than included in every status event. Its `profile` is the live display and workspace state in the same shape accepted by `preview` and `save`; `profiles` contains the complete saved profiles for profile browsers. `workspace_plan` contains the resolved workspace assignments for the editable live profile, while `profile_workspace_plans` maps every saved profile name to its resolved assignments so read-only browsers can preview the same plan without reimplementing workspace strategies. `displays` adds supported modes, focus, DPMS, active workspace, internal/external type, and physical panel size for each connected output. `source_profile` is present only when the live state exactly matches one saved profile. Settings that Hyprland cannot report back reliably, such as ICC and HDR luminance overrides, are preserved from that profile or from the best hardware match so an editor does not erase advanced configuration it never displayed. `edit_profile` applies one typed edit to a client-owned draft. Display mode, scale, VRR, transform, mirroring, position, enablement, color/HDR/ICC settings, and workspace settings are normalized and validated by the same profile geometry used by the bundled TUI. Resize edits move only displays attached to the resized display: its row beyond the old right edge, its column beyond the old bottom edge, displays on its corners, displays continuing those rows and columns, and any display a moving one would land on. Being stacked above or below a moving display in another row does not by itself move a display, and mirrors and modeless outputs never move; dragged position edits can request edge snapping with `snap_distance`, and every remaining collision is placed on the nearest clear outside edge. This also applies to enablement, typed positions, nudges, unmirroring, and resize edits. The edited display moves first, preserving unaffected displays; pre-existing collisions are cleared too. Disabled, mirrored, and modeless outputs occupy no independent area. The request and response schema is unchanged: existing panels consume the returned reflowed profile without frontend changes. Older daemons retain overlap rejection until upgraded. The method is stateless and does not touch the live displays until the returned profile is sent to `preview`. `scale_info` describes one scale on one mode, so an editor never computes sharpness itself. It is stateless and needs no displays. The result carries `presets` (the Scale row's pills for that mode), `options` (every sharp scale from 1 to 4, plus the sharp scale closest to `scale` when that is outside the list), `scale` as a profile stores it, `sharp`, `logical` (the logical width and height; whole pixels when sharp), and `apply`, the scale typed entry applies. A blurry scale also carries `closest` and `closest_logical` when a sharp scale exists for the mode. A `scale` outside 0.25 to 4 is an error (`scale must be between 0.25 and 4`), and so is a missing mode. Clients label a scale that is not sharp **Blurry**. For example: ```json {"scale": 1.33, "sharp": false, "logical": [2887.22, 1624.06], "closest": 1.33333, "closest_logical": [2880, 1620], "apply": 1.33333, "presets": [1, 1.25, 1.5, 1.6, 2, 3], "options": [1, 1.06667, 1.2, "..."]} ``` An `edit_profile` scale edit may add `snap_scale: true`: the daemon then stores the closest sharp scale instead of a blurry typed one, judged on the output's mode after any `mode` in the same edit. This is how typed entry applies a scale in both editors. Daemons older than `scale_info` answer it with an `unknown IPC method` error and ignore `snap_scale`. The typed Go client refuses to send `snap_scale` to such a daemon instead of letting it store a blurry scale. The Omarchy panel treats the unknown-method reply as missing support: it shows no preset pills, no ⚠ Blurry marker and no Custom… entry, and its More list falls back to the editor display's `scale_options` (the sharp list for the live mode), so it never shows a sharpness verdict it did not get from Go. Editor `displays` keep `scale_options` for those clients. ## Connecting displays and query timeouts Monitor and workspace-rule reads have a 750 ms deadline per query by default. A slow compositor or blocked DRM identity probe returns `error.code = "compositor_busy"` with a human-readable connecting message. No stale or partially enriched hardware snapshot is substituted for a successful response. Status and editor-state responses include an additive `monitor_set_hash`. Treat it as an opaque equality token for the output keys and their current connector bindings; it includes the connector paths used to distinguish otherwise identical outputs. It excludes layout, focus and power state. These daemon reads check hardware before and after reading workspace rules and return `compositor_busy` if the bindings changed. They therefore perform two monitor queries and one workspace-rule query; the 750 ms limit is per query, not a total response-time guarantee. Clients should retain the last visible snapshot while connecting, show the message, and retry while visible with at most one request in flight. Do not treat a failed refresh as an empty display list. Compare editor hashes with the latest status hash when both are present, and discard mismatches. Also track observed topology changes locally and reject requests from an older generation, including a change away and back to the same hardware. The hash is not an event counter or an atomic snapshot guarantee. Older daemons omit it; clients can fall back to their available identity/signature fields. Stateless `edit_profile` replies do not include a fresh hardware hash. Known-profile apply and rollback retain their existing serialized lifecycle. ## Enabling a sleeping output Preview apply wakes connected outputs that transition from disabled to enabled, using a targeted DPMS request and at most three attempts within the existing apply verification window. Confirmation starts only after those outputs report awake. Failure follows normal apply rollback, including restoring the previous disabled state. Already-enabled sleeping outputs are not woken by unrelated edits. The wire schema is unchanged; existing panel clients receive the existing preview success or apply error response. Older backends do not perform this wake check. --- # About hyprmoncfg Canonical URL: https://hyprmoncfg.dev/about/ hyprmoncfg lets you visually create multi-monitor layouts for Hyprland, save each setup as a profile, and switch profiles automatically on hotplug and lid events. It ships as two compiled Go binaries with no graphical toolkit or runtime dependency beyond Hyprland. The canonical source repository is [crmne/hyprmoncfg](https://github.com/crmne/hyprmoncfg). Packages are published in the AUR as [hyprmoncfg](https://aur.archlinux.org/packages/hyprmoncfg) and [hyprmoncfg-git](https://aur.archlinux.org/packages/hyprmoncfg-git), [Fedora COPR](https://copr.fedorainfracloud.org/coprs/paolino/hyprmoncfg/), [Nixpkgs](https://github.com/NixOS/nixpkgs/tree/master/pkgs/by-name/hy/hyprmoncfg), [Gentoo GURU](https://github.com/gentoo/guru/tree/master/gui-apps/hyprmoncfg), and unofficially for Void Linux through [Blackhole-vl](https://github.com/Event-Horizon-VL/blackhole-vl). hyprmoncfg is created by [Carmine Paolino](https://paolino.me/).