Plan workspaces across a laptop and an external monitor

On the laptop, workspace 1 holds code and workspace 2 holds reference material. At a desk, you want code on the larger screen and reference on the laptop. After unplugging, both tasks should remain accessible. This requires a workspace plan, not just the right display resolution.

The examples follow the pinned 4.0.0.alpha source and Lua dispatchers. Discover your own output names and bindings. eDP-1, DP-1 and workspace numbers below are teaching labels, not facts about your hardware. First make both displays usable with display geometry and scaling.

1. Four identities explain most confusion

application → one or more windows
window → belongs to a workspace
workspace → assigned to a monitor
monitor → has a position and scale in the desktop coordinate space

Operation	What moves	What stays together
Focus another monitor	Keyboard focus	Windows and workspaces stay placed
Move a window to workspace 2	One selected window	Other windows in its former workspace stay
Move workspace 1 to another monitor	Its whole task surface	Windows belonging to that workspace
Switch workspace layout	Arrangement inside a workspace	Its number and task role

Workspace 1 is not “workspace 1 on each monitor.” Ordinary numeric IDs identify workspaces across the session. Each monitor can show an active workspace, but the same ordinary workspace is not simultaneously duplicated on both displays.

A special scratchpad and a pinned floating window are separate cases. The scratchpad can cover the ordinary workspace; a pinned floating window can follow workspace changes on its monitor. Do not use these exceptions as the model for all windows.

2. Start with a plan that works on one screen

Workspace	Role	Laptop alone	At the desk
1	Editor and working terminal	Laptop	External display
2	Browser and documentation	Laptop	Laptop
3	Chat or occasional tools	Laptop, when needed	Whichever screen you choose

Keep the numbers tied to tasks rather than connector names. The same shortcuts then remain useful when the dock is unavailable. Do not initially reserve ten workspaces per monitor: first learn whether your actual work needs those groups.

Record the current state before moving test windows:

hyprctl monitors -j
hyprctl workspaces -j
hyprctl clients -j
omarchy menu keybindings --print

In the output, relate monitor name and position, workspace ID and monitor, then each window’s class/title and workspace. A shortened teaching inventory might be:

eDP-1: workspace 2, position 0x0
DP-1:  workspace 1, position 1440x0
editor window: workspace 1
browser window: workspace 2

Keep this inventory local; titles can contain personal filenames or messages. An empty workspace may disappear when inactive unless configured persistent. A missing empty workspace in the query is not evidence of lost data.

3. Connect the external screen and move the task

Connect with the lid open. Query monitors again and confirm both are enabled and arranged as intended. Physical “right” and configured “right” can differ; directional monitor actions use the configured desktop geometry.

Focus workspace 1 with its verified workspace shortcut. In the pinned defaults, Super + Shift + Alt + Right moves the active workspace to the monitor on the right. If your external screen is on the left, use the matching direction instead. This keeps the editor and its terminal together.

If you prefer an explicit command and the actual external name is DP-1, on the intended active workspace:

hyprctl dispatch 'hl.dsp.workspace.move({ monitor = "DP-1" })'

This targets the current workspace, not every workspace and not an inactive workspace guessed by title. Immediately inspect hyprctl activeworkspace and hyprctl workspaces -j; confirm the intended ID now names the external monitor. Do not repeatedly issue the move while unsure what is active. Shipped move bindings

Now use the verified Ctrl + Alt + Tab monitor-focus action to reach the laptop, then select workspace 2. Check that code remains visible on the external screen and docs remain visible on the laptop. If selecting a workspace focuses the other display, inspect where that workspace lives; switching does not mean cloning it onto the focused display.

4. Move one window without moving the whole task

Suppose a browser window belongs with the coding task. Focus only that window, then move it to workspace 1. The pinned Super + Shift + 1 moves and follows; Super + Shift + Alt + 1 moves silently.

-- These are existing-action equivalents, not lines to add as duplicate bindings.
hl.dsp.window.move({ workspace = "1" })
hl.dsp.window.move({ workspace = "1", follow = false })

The silent action avoids leaving the current task, but it can look like a disappearance. Check the destination workspace. It does not move all browser windows, and it does not mean “send to monitor 1.”

Window startup rules such as workspace = "3 silent" control newly created matching windows. They do not continuously enforce an entire monitor policy, and single-instance apps may reuse old windows. Use window-rule diagnostics before adding automatic placement.

5. Disconnect and recover by identity

Save work, unplug with the laptop lid open, then query the three inventories again. In the normal compositor flow, workspaces on a removed output are reassigned to remaining outputs. Confirm the result rather than assuming the desktop arrangement is restored exactly. Omarchy’s monitor watcher also reconciles clamshell and output state; it is not a promise to recreate your custom workspace plan. Monitor watcher

Try workspace 1, then workspace 2. You should be able to access code and docs sequentially on the laptop. If one seems missing:

1. Check hyprctl clients for its title/class and workspace.
2. Switch to that ordinary workspace with its verified shortcut.
3. If it is in the scratchpad, reveal the scratchpad instead.
4. If the workspace is scrolling, navigate to the window outside the viewport.
5. If the window is grouped, select its group member.

Do not reopen the app until you know whether the old window exists. Another instance can obscure the real issue and risk confusing unsaved work.

If the output itself is missing or disabled, that is a display problem. Use display troubleshooting. If the monitor exists but your chosen workspace was moved, use the appropriate workspace move. Restarting the entire graphical session is a much broader action than either repair.

Reconnect and repeat the manual task move. A predictable manual plan is a useful baseline before adding automated docking scripts.

6. Add fixed assignment only when its scope matches your setup

For an external monitor that is routinely present on a desktop, you may want workspace 1 bound to it. Back up the personal file you will use; if placing the rule in monitors.lua, confirm the main entry loads it. With the verified monitor name:

hl.workspace_rule({ workspace = "1", monitor = "DP-1" })

This is an assignment rule, not the same as the one-time move. Test it with a new test workspace/session after saving work; do not assume a reload rearranges every open workspace exactly as expected. Existing rules and output availability matter. Hyprland workspace rules

For a laptop that is often undocked, start with manual moves instead of unconditional pinning to an absent connector. “Persistent” keeps an empty workspace alive; it does not make an absent monitor exist or store application contents. Avoid adding persistent, default and monitor bindings together without a separate reason for each.

Connector names can change when using another port or dock. A desc: monitor selector can help when the description uniquely identifies the screen, but identical displays or changing EDID descriptions can still be ambiguous. Discover both names and descriptions through hyprctl monitors all; never copy a manufacturer’s description from someone else’s setup.

Automatic profiles should account for output presence, startup versus hotplug, open/closed lid and a reachable fallback. That is a separate extension, not something this simple fixed rule guarantees. Do not run another monitor daemon alongside Omarchy’s watcher without understanding which process owns each change.

7. Distinguish saved layout from saved location

Per-workspace layout is saved separately by Omarchy. Moving workspace 1 between screens can preserve its layout choice without restoring your old monitor assignment after the next hotplug. A stable number, a stable layout, and a stable physical screen are three different preferences.

Also compare logical space: a scrolling column sized usefully on the external display may feel narrow on the laptop. First inspect scale and window layout; do not compensate by rewriting every app’s font size each time you unplug. See layout selection and text size.

8. Restore and check the whole connection cycle

Remove only your added assignment rule, compare later edits before restoring a backup, and reload through the menu. Move the test windows or task workspaces back to the recorded screens. Removing a future assignment rule is not itself a command to return every current workspace to its old monitor.

Verify laptop alone → both screens → laptop alone again. Check the same code, browser and terminal windows rather than just the top bar’s workspace marks. For clamshell work, first verify the open-lid cycle, then read lid and sleep behaviour; a lid event changes both security and display handling.

Your success criterion is that each task remains reachable with a known action and no duplicate app launch. This guide is source-reviewed; unplug, dock and lid behaviour still require testing on your actual hardware.