---
title: Workspace Session Recovery
description: Capture and restore Hyprland window sessions after restarts, crashes, or layout experiments.
sidebar:
  order: 5
---

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.

:::note
This is best-effort recovery. Hyprland can move and resize windows, but some application state still belongs to the application itself.
:::

## Capture a session

Capture every visible workspace:

```bash
dot workspace-capture
```

Capture only the active workspace:

```bash
dot workspace-capture --current-workspace
```

By default captures are written to:

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

The command also writes a capture log to:

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

To write a named capture:

```bash
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:

```bash
dot workspace-restore --dry-run
```

Restore the newest capture from the state directory:

```bash
dot workspace-restore
```

Restore a specific file:

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

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

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

The restore log is written to:

```text
~/.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:

```text
${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.

## Workspace menu

The Omarchy menu wraps the common actions:

```bash
workspace-menu
```

The shared Hypr binding is:

```text
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

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

## Troubleshooting

If nothing restores, check that a capture exists:

```bash
ls ~/.local/state/workspace-sessions
```

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

```bash
dot workspace-restore --no-launch
```

If restore launches apps but leaves current placement alone:

```bash
dot workspace-restore --no-move
```

If you want to inspect one capture directly:

```bash
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=...`.