Workspace Keeper (technical)

Remembers which COSMIC workspace each window is on and moves windows back after a login or a compositor crash. User overview: ws-keeper/README.md.

How it works

Installed files

./install.sh ws-keeper sets up:

Path What
~/.local/lib/ws-keeper Link to ws-keeper/ in the repo checkout
~/.local/bin/ws-keeper Wrapper that runs ws-keeper.py with python3 -I
~/.config/systemd/user/ws-keeper-watch.service ws-keeper watch for the whole desktop session, restarted 10 s after a failure
~/.config/systemd/user/ws-keeper-restore.service At login: waits 15 s, then ws-keeper restore --watch 180

At run time it writes the snapshots to ~/.local/state/ws-keeper/. ./install.sh --uninstall ws-keeper stops and removes the services, the wrapper and the link.

Commands

ws-keeper list                  windows and their workspace now
ws-keeper watch                 snapshot whenever windows change (run by ws-keeper-watch.service)
ws-keeper save                  take a snapshot now
ws-keeper restore               move windows back using the newest snapshot from before this session
ws-keeper restore --latest      same, from the newest snapshot (fix-up after you moved things by mistake)
ws-keeper restore --watch S     keep matching new windows for S seconds (used at login)
ws-keeper restore --dry-run     print the moves, do not move
ws-keeper snapshots             stored snapshots (~/.local/state/ws-keeper)
ws-keeper pins                  pin rules, whether each workspace exists, app ids of open windows

Tests (no Wayland session needed): python3 -m unittest discover -s ws-keeper -v and python3 -m unittest discover -s lib -v (lib/test_wsk.py).

Configuration

Pins

File: $XDG_CONFIG_HOME/ws-keeper/pins (default ~/.config/ws-keeper/pins). A missing file means no pins. The taskbar’s context menu writes it; you can also edit it by hand.

# app_id = Workspace Name
org.example.Chat = Work
org.example.Mail = Mail

Constants

The snapshot count (KEEP), skipped apps (SKIP_APPS) and the watch delays (DEBOUNCE, MAX_WAIT, SLOW, LOGIN_GRACE) are constants in ws-keeper.py.

Logs: journalctl --user -u ws-keeper-watch and journalctl --user -u ws-keeper-restore.

Limits