Taming Multi-Monitor Hotplugging with Hyprland, Kanshi, and Waybar

I run Arch Linux with Hyprland on my ThinkPad X1 Carbon 11th gen, and for the longest time, docking and undocking was a hassle. My goal was simple: I wanted a seamless transition between my triple-monitor home office setup and my mobile laptop setup, without restarting my session or losing track of my workspaces.

The main challenge was the "split brain" problem. Hyprland manages the workspaces, but Waybar has its own config that can easily get out of sync. If I hardcoded workspaces in Waybar, they would stick around even when the monitor they belonged to was disconnected. On top of that, reconnecting my dock (which uses a mix of HDMI and DisplayPort) often caused race conditions where scripts would fire before the monitors were fully recognized.

Here is how I solved it using kanshi, uwsm, and a custom Zsh script.

1. The Strategy: Dynamic Workspace Assignment

Instead of hardcoding workspaces to monitors in hyprland.conf or waybar/config.jsonc, I moved that logic into a script that runs whenever kanshi detects a profile change.

I removed the persistent-workspaces block from my Waybar config entirely. Now, Waybar simply listens to Hyprland. If Hyprland says "Workspace 1 is on HDMI-A-1," Waybar displays it there. This eliminated the conflict immediately.

2. The Logic: A Smarter Script

I wrote a script, multihead.zsh, that serves as the bridge between Kanshi and Hyprland.

• Serial Number Detection: Since port names (like DP-6 vs DP-7) can change depending on how the dock enumerates devices, I stopped using them. My script now uses jq to look up the connected monitors by their unique Serial Numbers.
• Race Condition Fix: I added a "wait loop" to the script. When I plug in the dock, the script pauses and checks for the monitors to actually appear in Hyprland's device list before trying to assign workspaces. This prevents the "all workspaces dumped on laptop screen" bug.
• Two-Stage Docking: My dock detects the connected monitors in stages (one monitor first, then the second). I set up a fix_me profile in Kanshi that acts as a safe fallback, forcing everything to the laptop screen until the full home_office profile triggers a second later.

3. The Result

Now, when I undock, my "Home Office" workspaces (Browser, Shell, Work, Jobs) automatically snap back to my laptop screen. When I sit back down and plug in a single USB-C cable, the script waits for the monitors to wake up, identifies which is which by serial number, and moves my workspaces back to their designated external screens—all without logging out or restarting Hyprland.

It’s finally the "plug and play" experience I wanted on a tiling window manager.

TODO

• Cleanup Hyprland, Waybar, and Kanshi configs
• Post to personal Gitea repos (each config will be a submodule for my dotfiles)