Hyprland Multi-Monitor Workspaces

Bash Hyprland v0.41.2 C++ plugin 0 failures @ 10k ops 0 failures @ 1400 edge cases

GitHub: stevenvo780/hyprland-multi-monitor-workspaces

---

What it is

A production-ready Hyprland configuration snapshot for multi-monitor multitasking. The core problem it solves: by default, Hyprland workspace numbers are global — switching workspace 3 on monitor A can yank the view on monitor B. This config, built around the split-monitor-workspaces plugin, makes each monitor manage its own independent workspace set.

It also adds a strict per-monitor workspace limit layer via split-dispatch-strict.sh, enforcing a 2/3/4 cap even in plugin versions that lack native per-monitor limits (v1.1.0).

Published stress-test results: zero failures across 10 000 sequential operations and 2 600 parallel operations.

---

What’s included

hypr/
  hyprland.conf                        main config entry point
  conf.d/
    99-split-monitor-workspaces.conf   plugin load + keybinds
  scripts/
    load-split-plugin.sh               loads the compiled .so at Hyprland startup
    split-dispatch-strict.sh           enforces per-monitor workspace caps
    split-limit-adjust.sh              adjust caps dynamically at runtime
    split-ws-setup.sh                  initial workspace assignment on login

scripts/
  build-plugin.sh        compiles the plugin pinned to a specific commit
  deploy-config.sh       installs config to ~/.config/hypr/
  stress-headless.sh     automated stress test harness (headless Hyprland)
  edgecases-headless.sh  edge-case battery (invalid inputs, corrupt state)

---

Per-monitor workspace caps

split-dispatch-strict.sh intercepts workspace switch requests and clamps them to these limits regardless of what the plugin exposes natively:

Monitor	Max local workspaces
Monitor 1	2
Monitor 2	3
Monitor 3+	4

Caps are adjustable at runtime with split-limit-adjust.sh — no restart needed.

---

Available dispatchers

After loading the plugin:

Dispatcher	Effect
split-workspace	Switch to a workspace on the current monitor
split-movetoworkspace	Move focused window to a workspace (follow it)
split-movetoworkspacesilent	Move focused window without following
split-changemonitor	Move focus to another monitor
split-changemonitorsilent	Move focus to another monitor silently

---

Target versions

Component	Pinned version
Hyprland	v0.41.2
split-monitor-workspaces	commit a03a32c6e0f64c05c093ced864a326b4ab58eabf

---

Quick start

1. Build plugin

git clone https://github.com/stevenvo780/hyprland-multi-monitor-workspaces.git
cd hyprland-multi-monitor-workspaces
./scripts/build-plugin.sh

Compiles the plugin .so pinned to the specific commit above against your installed Hyprland headers.

2. Deploy config

./scripts/deploy-config.sh
# Installs to ~/.config/hypr/
# Your existing config is backed up before any file is written.

3. Verify

# After starting a Hyprland session:
hyprctl plugin list
hyprctl binds | grep split-

Expected output: split-monitor-workspaces listed; split-workspace, split-movetoworkspace, etc. present in binds.

4. Run stress tests

./scripts/stress-headless.sh
./scripts/edgecases-headless.sh

Both run against headless Hyprland instances. See results table below.

---

Stress test results (2026-02-26)

Suite	Parameters	Failures
Stress A	RESTART_CYCLES=30, SEQ_OPS=6000, PAR_WORKERS=12, PAR_OPS=1800	0
Stress B	RESTART_CYCLES=50, SEQ_OPS=10000, PAR_WORKERS=16, PAR_OPS=2600	0
Edge A	OUTPUT_MATRIX='1 2 3 5', RAPID_ITERS=500	0
Edge B	OUTPUT_MATRIX='3 5', RAPID_ITERS=1400	0

Edge cases covered by the test battery:

• Default clamp (2/3/4) with 1, 2, 3, and 5 monitors
• Invalid inputs: 0, negative numbers, text, empty string, 999999
• Dynamic limit adjustments at boundary values (1 and 10)
• Corrupt split-limits.json with automatic recovery
• Missing plugin .so (graceful degradation — no crash)
• Stale monitor keys in the limits file

Headless socket path gotcha

On headless Hyprland 0.41.2, a long XDG_RUNTIME_DIR can overflow the socket path and crash the session. The test harness uses short paths under /tmp/hs* to avoid false negatives in CI / headless environments.

---

Community

This config is designed for submission to:

• awesome-hyprland — the community list of Hyprland resources
• r/hyprland — active community of Hyprland users

Issues and PRs welcome — every desktop setup is a little different.

---

Stack

Component	Technology
Compositor	Hyprland v0.41.2
Plugin	split-monitor-workspaces (C++), pinned commit
Config language	Hyprland config (TOML-like)
Scripts	Bash
Test harness	Headless Hyprland + Bash (stress-headless.sh, edgecases-headless.sh)