Workspace Session Recovery

Capture and restore Hyprland window sessions after restarts, crashes, or layout experiments.

The dot workspace session commands save the current Hyprland clients to JSON, then restore the latest capture by moving existing windows back to their saved workspaces and relaunching supported missing apps. The old workspace-capture and workspace-restore names remain as compatibility wrappers.

Use this before risky layout work, before restarting Hyprland, or when you want a quick recovery point for open workspaces.

Capture a session

Capture every visible workspace:

dot workspace-capture

Capture only the active workspace:

dot workspace-capture --current-workspace

By default captures are written to:

~/.local/state/workspace-sessions/workspace-<timestamp>.json

The command also writes a capture log to:

~/.local/state/workspace-sessions/capture.log

To write a named capture:

dot workspace-capture --output=~/workspace-before-restart.json

Restore safely

Start with a dry run. It prints the restore plan without launching or moving windows:

dot workspace-restore --dry-run

Restore the newest capture from the state directory:

dot workspace-restore

Restore a specific file:

dot workspace-restore --file=~/workspace-before-restart.json

Search a different state directory for the newest capture and write restore.log there:

dot workspace-restore --state-dir=~/somewhere

The restore log is written to:

~/.local/state/workspace-sessions/restore.log

What gets restored

The restore command reads hyprctl -j clients and tries these paths in order:

Reuse a still-running window by saved address.
Match an existing window by class and workspace.
Launch a supported missing app, then move it to the saved workspace.
Restore floating geometry or tiled size when the saved client has enough geometry data.
Switch back to the saved active workspace at the end.

Reusable relaunch support covers Twitch webapps, generic Chrome webapps with captured URLs, and Ghostty terminals. Ghostty launches through ghostty-host-config to keep the active config.$OMARCHY_HOST override, and passes --working-directory when the saved directory still exists.

Personal Chromium and work Chrome launch policy is optional private data in ~/.config/dotfiles-private/workspace-session.json. Each rule matches captured window classes and supplies an executable plus argument list. Without that file, existing windows can still be reused by saved address and the reusable public relaunch paths still work.

Captured browser URLs are passed to the Hyprland launcher as one shell-quoted argument, so query strings and shell metacharacters are preserved as URL data rather than interpreted as commands.

Unsupported classes are skipped with a reason in the restore output.

Browser URLs

dot workspace-capture can attach a real browser URL when the browser URL state file exists:

${XDG_STATE_HOME:-~/.local/state}/browser-urls.json

When that file is missing, Chromium windows can still be matched or relaunched by class, but generic webapp URL recovery is limited.

The Omarchy menu wraps the common actions:

workspace-menu

The shared Hypr binding is:

SUPER+ALT+W

It offers capture, dry-run restore, restore, and relayout actions. On the desktop host it also exposes the host-specific workspace setup action.

Recovery flow

Run dot workspace-capture before the risky change.
Make the change, restart Hyprland, or recover from the crash.
Run dot workspace-restore --dry-run and read the plan.
Run dot workspace-restore when the plan looks safe.
Check restore.log for skipped windows.

Troubleshooting

If nothing restores, check that a capture exists:

ls ~/.local/state/workspace-sessions

If restore launches too much, try moving only existing windows:

dot workspace-restore --no-launch

If restore launches apps but leaves current placement alone:

dot workspace-restore --no-move

If you want to inspect one capture directly:

jq '.clients[] | {workspace: .workspace.id, class, title, browser_url}' ~/.local/state/workspace-sessions/workspace-*.json

Rollback

The restore command only moves, resizes, and launches windows. There is no persistent layout state to undo. Move windows manually or rerun a better capture file with --file=....