Linked workspaces for a dual-monitor Omarchy setup

[Chimmy89]

omarchy-linked-workspaces-writeup.md

Linked workspaces for a dual-monitor Omarchy setup (+ two gotchas that took a while to track down)

I run two screens (a primary monitor + a secondary display) and wanted SUPER+N to flip both screens to "the same" workspace at once, instead of the stock 1–5 / 6–10 split where each screen owns its own fixed set. Hyprland doesn't support one workspace spanning two monitors natively (confirmed in hyprwm/Hyprland#10088 — "you can't do that"), so this fakes it by pairing two real workspaces and flipping them together. There's an existing simple version of this idea (Omarchy-Two-Monitor-Workspace-Switch-for-Hyprland), but it's fixed at 5 pairs, uses old-style .conf binds, and always ends focus on the second monitor regardless of which screen you were using. This version:

• scales to 10 pairs (SUPER+1..SUPER+0)
• keeps you on whichever physical screen you were already using after a switch
• has a bar widget that shows one button per pair (not per raw workspace)
• lets you rename a pair by hand with a small popup
• survived a stress test that reliably broke the naive version

That last point is the reason for the post — I hit two real bugs building this, both with symptoms that only show up under fast switching, and I couldn't find either documented anywhere. Writing them up in case they save someone else the debugging time.

The setup

1. Pin the raw workspaces to their monitors (hypr/monitors.lua):

local primary = "desc:YOUR_PRIMARY_MONITOR"     -- see `hyprctl monitors -j` for the desc string
local secondary = "desc:YOUR_SECONDARY_MONITOR"

hl.monitor({ output = primary, mode = "...", position = "0x0", scale = 1 })
hl.monitor({ output = secondary, mode = "...", position = "...", scale = 1 })

-- Pair N = raw workspace N (primary) + raw workspace N+10 (secondary).
-- Pinning is what makes this work at all -- without it Hyprland drags a
-- workspace to whichever monitor is focused when you switch to it.
for pair = 1, 10 do
  hl.workspace_rule({ workspace = tostring(pair), monitor = primary, default = (pair == 1) })
  hl.workspace_rule({ workspace = tostring(pair + 10), monitor = secondary, default = (pair == 1) })
end

2. The linking logic (hypr/linked-workspaces.lua, required from hyprland.lua):

-- Linked workspaces: make both monitors behave like one workspace.
--
-- Hyprland gives every workspace exactly one monitor, so a workspace spanning
-- both screens has to be faked by pairing two real ones. hypr/monitors.lua
-- pins the halves: the primary owns 1..10, the secondary owns 11..20.
--
--   pair 3  ==  workspace 3 on the primary  +  workspace 13 on the secondary
--
-- SUPER+3 flips both screens to pair 3 and leaves focus on whichever monitor
-- already had it. SUPER+SHIFT+3 sends the window to pair 3 on the screen it
-- is already on, so windows change workspace without changing monitor.

local PAIR_OFFSET = 10
local PAIRS = 10

local function offset_for(id)
  if id and id > PAIR_OFFSET and id <= PAIR_OFFSET + PAIRS then
    return PAIR_OFFSET
  end
  return 0
end

local function active_offset()
  local workspace = hl.get_active_workspace()
  return offset_for(workspace and workspace.id)
end

local function active_pair()
  local workspace = hl.get_active_workspace()
  local id = workspace and workspace.id
  if not id or id < 1 or id > PAIR_OFFSET + PAIRS then
    return nil
  end
  return id - offset_for(id)
end

local function multi_monitor()
  local monitors = hl.get_monitors()
  return monitors ~= nil and #monitors > 1
end

-- Put the unfocused monitor on its half of pair `n`. This briefly steals
-- global focus, but the caller's own final dispatch always refocuses
-- `n + offset` right after -- deterministically the correct monitor+workspace,
-- since offset was captured once at the start of the call. See Gotcha #1
-- below for why this function does NOT also try to "restore" the previously
-- active monitor by name.
local function sync_other_monitor(n, offset)
  if not multi_monitor() then
    return
  end
  local other = (offset == 0) and (n + PAIR_OFFSET) or n
  hl.dispatch(hl.dsp.focus({ workspace = tostring(other) }))
end

-- See Gotcha #2 below for why this settle-time guard exists.
local MIN_SETTLE_MS = 20
local switch_busy = false
local switch_pending = nil

local function show(n)
  if switch_busy then
    switch_pending = n
    return
  end

  switch_busy = true
  local offset = active_offset()
  sync_other_monitor(n, offset)
  hl.dispatch(hl.dsp.focus({ workspace = tostring(n + offset) }))

  hl.timer(function()
    switch_busy = false
    if switch_pending then
      local queued = switch_pending
      switch_pending = nil
      show(queued)
    end
  end, { timeout = MIN_SETTLE_MS, type = "oneshot" })
end

local function switch(n)
  return function() show(n) end
end

local function move(n, follow)
  return function()
    local offset = active_offset()
    if follow then
      sync_other_monitor(n, offset)
    end
    hl.dispatch(hl.dsp.window.move({ workspace = tostring(n + offset), follow = follow }))
  end
end

-- Pairs holding at least one window on either screen, for prev/next stepping.
local function occupied_pairs()
  local occupied = {}
  for _, workspace in ipairs(hl.get_workspaces() or {}) do
    local id = workspace.id
    if id and id >= 1 and id <= PAIR_OFFSET + PAIRS then
      local windows = hl.get_workspace_windows(workspace)
      if windows and #windows > 0 then
        occupied[id - offset_for(id)] = true
      end
    end
  end
  return occupied
end

local function step(delta)
  return function()
    local current = active_pair()
    if not current then return end
    local occupied = occupied_pairs()
    for hop = 1, PAIRS do
      local n = ((current - 1 + delta * hop) % PAIRS) + 1
      if occupied[n] then
        show(n)
        return
      end
    end
  end
end

local function move_step(delta)
  return function()
    local current = active_pair()
    if not current then return end
    move(((current - 1 + delta) % PAIRS) + 1, true)()
  end
end

-- Send the focused window to the other screen without leaving the pair.
local function move_to_half(wanted)
  return function()
    local pair = active_pair()
    if not pair or not multi_monitor() or active_offset() == wanted then
      return
    end
    hl.dispatch(hl.dsp.window.move({ workspace = tostring(pair + wanted) }))
  end
end

-- Replace Omarchy's per-workspace bindings with the linked equivalents.
for pair = 1, PAIRS do
  local key = "code:" .. tostring(pair + 9)
  hl.unbind("SUPER + " .. key)
  hl.unbind("SUPER + SHIFT + " .. key)
  hl.unbind("SUPER + SHIFT + ALT + " .. key)

  o.bind("SUPER + " .. key, "Switch to pair " .. pair .. " (both screens)", switch(pair))
  o.bind("SUPER + SHIFT + " .. key, "Move window to pair " .. pair, move(pair, true))
  o.bind("SUPER + SHIFT + ALT + " .. key, "Move window silently to pair " .. pair, move(pair, false))
end

hl.unbind("SUPER + TAB")
hl.unbind("SUPER + SHIFT + TAB")
hl.unbind("SUPER + mouse_down")
hl.unbind("SUPER + mouse_up")
o.bind("SUPER + TAB", "Next pair (both screens)", step(1))
o.bind("SUPER + SHIFT + TAB", "Previous pair (both screens)", step(-1))
o.bind("SUPER + mouse_down", "Scroll pair forward", step(1))
o.bind("SUPER + mouse_up", "Scroll pair backward", step(-1))

o.bind("SUPER + CTRL + SHIFT + RIGHT", "Move window to next pair", move_step(1))
o.bind("SUPER + CTRL + SHIFT + LEFT", "Move window to previous pair", move_step(-1))
o.bind("SUPER + CTRL + UP", "Move window to the secondary screen", move_to_half(PAIR_OFFSET))
o.bind("SUPER + CTRL + DOWN", "Move window to the primary screen", move_to_half(0))

-- Exported so a bar widget can call linked_workspaces.show(3) on click, and
-- so other bindings (e.g. a rename hotkey) can read the current pair.
_G.linked_workspaces = { show = show, active_pair = active_pair, pairs_count = PAIRS, pair_offset = PAIR_OFFSET }

3. Optional: rename a pair by hand. A small SUPER+SHIFT+ALT+N binding that pops a gum input prompt and renames both halves:

-- hypr/bindings.lua
o.bind("SUPER + SHIFT + ALT + N", "Rename workspace pair", function()
  local pair = linked_workspaces.active_pair()
  if not pair then return end

  hl.dispatch(hl.dsp.exec_cmd(
    "[float;size 460 120;center] foot -a rename-workspace-prompt -e "
      .. os.getenv("HOME")
      .. "/.local/bin/rename-workspace-pair "
      .. tostring(pair)
  ))
end)

#!/usr/bin/env bash
# ~/.local/bin/rename-workspace-pair
set -euo pipefail
PAIR="$1"
PAIR_OFFSET=10
MAX_LEN=12

name=$(gum input --placeholder "Workspace name" --char-limit "$MAX_LEN" --width 40)
[ -z "$name" ] && exit 0

name=${name:0:$MAX_LEN}
name=${name//\"/}
name=${name//\\/}

for raw in "$PAIR" "$((PAIR + PAIR_OFFSET))"; do
  hyprctl dispatch "hl.dsp.workspace.rename({ workspace = \"$raw\", name = \"$name\" })" >/dev/null
done

If some pairs should always be visible in your bar regardless of whether they're occupied, give both their raw halves persistent = true too, or Hyprland will tear down and recreate the empty half, dropping whatever name you gave it:

for _, pair in ipairs({ 1, 2, 3, 4, 5, 10 }) do  -- whichever pairs you always show
  hl.workspace_rule({ workspace = tostring(pair), persistent = true })
  hl.workspace_rule({ workspace = tostring(pair + 10), persistent = true })
end

4. Optional: a bar widget that shows pairs instead of raw workspace numbers. Clone omarchy.workspaces (omarchy plugin clone omarchy.workspaces) and replace its logic with something like:

import QtQuick
import QtQuick.Layouts
import Quickshell.Hyprland
import qs.Commons
import qs.Ui

BarWidget {
  id: root
  moduleName: "omarchy.workspaces"

  readonly property int pairOffset: 10

  function workspaceById(id) {
    var values = Hyprland.workspaces.values
    for (var i = 0; i < values.length; i++) {
      if (values[i].id === id) return values[i]
    }
    return null
  }

  function pairExists(pair) {
    return root.workspaceById(pair) !== null || root.workspaceById(pair + root.pairOffset) !== null
  }

  function pairOccupied(pair) {
    var a = root.workspaceById(pair)
    var b = root.workspaceById(pair + root.pairOffset)
    return (a !== null && a.toplevels.values.length > 0) || (b !== null && b.toplevels.values.length > 0)
  }

  // Real QML properties, not plain functions -- see Gotcha #3 below.
  readonly property int activePair: {
    var focused = Hyprland.focusedWorkspace
    if (!focused) return -1
    var id = focused.id
    if (id > root.pairOffset && id <= root.pairOffset + 10) return id - root.pairOffset
    if (id >= 1 && id <= 10) return id
    return -1
  }

  readonly property var pairIds: {
    var ids = [1, 2, 3, 4, 5, 10]  // always-shown pairs; adjust to taste
    var active = root.activePair
    for (var pair = 6; pair <= 9; pair++) {
      if (root.pairExists(pair) || active === pair) ids.push(pair)
    }
    ids.sort(function(left, right) { return left - right })
    return ids
  }

  function focusPair(pair) {
    if (!root.bar) return
    root.bar.run("hyprctl eval " + Util.shellQuote("linked_workspaces.show(" + pair + ")"))
  }

  readonly property real trailingGap: root.vertical ? 0 : Style.spaceReal(1.5)
  implicitWidth: grid.implicitWidth + trailingGap
  implicitHeight: grid.implicitHeight

  GridLayout {
    id: grid
    anchors.fill: parent
    anchors.rightMargin: root.trailingGap
    columns: root.vertical ? 1 : root.pairIds.length
    columnSpacing: root.vertical ? 0 : Style.space(1)
    rowSpacing: root.vertical ? Style.space(2) : 0

    Repeater {
      model: root.pairIds

      WidgetButton {
        required property int modelData
        readonly property var workspace: root.workspaceById(modelData)
        readonly property bool occupied: root.pairOccupied(modelData)
        readonly property bool focused: root.activePair === modelData
        readonly property string keyDigit: modelData === 10 ? "0" : String(modelData)
        readonly property string label: {
          var name = (workspace && workspace.name && workspace.name !== "") ? workspace.name : ""
          if (name === "") return keyDigit
          return name + " (" + keyDigit + ")"
        }

        bar: root.bar
        text: label
        active: focused
        opacity: occupied || focused ? 1 : 0.5
        horizontalMargin: 6
        verticalPadding: 6
        fixedWidth: root.vertical ? root.barSize : -1
        fixedHeight: root.barSize
        onPressed: function() { root.focusPair(modelData) }
      }
    }
  }
}

Three gotchas, in order of how long they took to find

Gotcha #1: hl.dsp.focus({monitor = name}) isn't a safe way to "restore" focus

My first version of sync_other_monitor captured hl.get_active_monitor()'s name before doing anything, moved the other monitor, then re-focused the captured name to "restore" where I was. Under fast switching this let the two screens end up on genuinely different pairs — caught it live: one screen on pair 7, the other still on pair 1.

The capture reads live, mutable state (hl.get_active_monitor()) that can be mid-flight from an overlapping call. Turns out it's also unnecessary: the caller's own final dispatch (show()'s last line) already refocuses n + offset, which is deterministically the correct monitor+workspace since offset was captured once at the top of that call. Dropped the capture-and-restore step entirely; the deterministic restore was already doing the same job without reading anything racy.

Related: if you have input.follow_mouse on (Hyprland's default), also set cursor:no_warps = true. Every hl.dsp.focus() call warps the cursor to its target by default, and with follow_mouse on, that warp immediately re-steals focus onto whatever's under the cursor there — corrupting the very next dispatch in the same sequence. This bit window moves specifically (SUPER+SHIFT+N), sending windows to the wrong screen or the wrong tile slot.

hl.config({
  cursor = {
    no_warps = true,
  },
})

Gotcha #2: a dispatch reporting "ok" doesn't mean the compositor's state has committed yet

This one was the strange one. Even with #1 fixed, fast switching (real key presses, not scripted) could still occasionally split the two monitors onto different pairs. I could not reproduce it reliably through hyprctl eval calls with any gap between them — only truly rapid, back-to-back calls triggered it.

Stress-tested it directly: calling show() for a list of pairs back-to-back with zero gap between calls failed ~90% of the time over dozens of trials. Every dispatch reported ok. Inserting a plain 10ms sleep between calls — no other change — dropped that to 0/40 desyncs, including under a deliberately adversarial parallel-dispatch burst that had failed heavily before. A pure Lua-level reentrancy guard (preventing the same function from running twice at once) did not fix it on its own, which is what pointed at timing rather than call-stack overlap: hyprctl's own docs already note that dispatch calls are meant to be spaced out or batched (--batch) rather than spammed individually, for exactly this class of reason.

Fix: show()'s busy flag isn't really about preventing re-entrancy — it enforces a minimum real-time gap (20ms, 2x the empirical threshold, for margin) after each call before the next is allowed to run, using hl.timer(fn, {timeout=20, type="oneshot"}) (non-blocking — a plain sleep here would freeze the whole compositor for the duration, since this runs inside a keybind callback). Anything that arrives during that window gets coalesced into switch_pending and replayed once the timer fires, so a fast burst just jumps straight to wherever you actually meant to end up.

Real key-repeat is typically 25–50ms between events, comfortably above the 20ms window, so this shouldn't be noticeable in normal use — it only engages under bursts faster than a human can plausibly produce by hand.

Gotcha #3: in Quickshell/QML, prefer real properties over plain functions for anything reactive

After both of the above were fixed, the bar's highlight itself got stuck showing a stale pair — permanently, while the rest of the bar (clock, tray) kept updating fine. Confirmed with a screenshot that this was purely cosmetic: Hyprland's actual state was correct throughout.

The widget had activePair() and pairIds() as plain JS functions, called from inside other property bindings (focused: root.activePair() === modelData). That's a binding depending on a function that itself reads a property — two layers removed from the actual reactive source (Hyprland.focusedWorkspace). QML's automatic dependency tracking through nested function calls is less reliable than direct property-to-property bindings; something about that chain let the binding permanently stop re-subscribing.

Fix: converted both to real QML properties (readonly property int activePair: {...}, readonly property var pairIds: {...}) instead of functions, so Hyprland's own property-change notifications drive them directly. Verified with actual screenshots across multiple rounds of rapid switching, landing on a different pair each time — not just "looks fixed once."

---

Happy to answer questions or help adapt this to a different monitor count/layout. The full config is above; swap in your own hyprctl monitors -j descriptor strings and you should be good to go.