Session Keeper

Save your open session and bring it back after a power cut.

Session Keeper snapshots what you have open — programs, terminals (with their working directories), and manually-started background servers — every 60 seconds to disk. After a power cut or crash, on your next login it offers to restore everything the way it was.

Built for GNOME on Wayland, zero external dependencies (Node.js only), all user-level (no root).

---

The Wayland reality (read this first)

You are on Wayland. Wayland deliberately does not let programs read or set exact window geometry — no tool can restore pixel-perfect window positions, and neither does this one. But what you actually care about works reliably:

Restored ✅	Not restored ❌
which programs were open	exact window position / size
terminals + each tab's folder	multi-monitor layout
browsers (+ tabs via --restore-last-session)	scroll position inside an app
manually-started background servers (node/python…)	unsaved work in an editor

Background services managed by systemd already come back on boot, so Session Keeper skips them to avoid duplicates.

How it works

capture.js  ── every 60s (systemd timer) ──►  ~/.local/share/session-keeper/latest.json
                reads /proc, classifies processes into buckets, writes atomically
                (a half-written file never survives a power cut)

restore.js  ── on login (autostart) ──►  offers restore IF the shutdown was not clean
                launches programs detached; NEVER kills anything;
                skips whatever is already running (no duplicates)

"Only after a power cut": a clean shutdown leaves a clean-shutdown marker (systemd ExecStop). A power cut never writes it, so restore knows the shutdown was dirty and offers to bring the session back. A clean reboot stays silent.

Requirements

• Linux with systemd (user services)
• Node.js (any recent version)
• Ptyxis terminal for terminal-tab restore (the default GNOME terminal on recent Ubuntu/Fedora). Other buckets work without it. Support for more terminals is on the roadmap.

Install

git clone https://github.com/brat91tvoj/session-keeper.git
cd session-keeper
bash install.sh

No root. Everything is installed as user systemd units + a GNOME autostart entry.

Usage

node restore.js               # preview the latest snapshot (dry-run, launches nothing)
node restore.js --yes         # restore everything now
node restore.js --interactive # show list + ask Y/n
node restore.js --only=terminals,browsers   # restore only certain buckets
node capture.js               # take a snapshot right now

systemctl --user status session-keeper.timer
journalctl --user -u session-keeper -n 20

Snapshot buckets

• browsers — chrome/firefox main process (+ profile, debug port, restore-last-session)
• terminals — Ptyxis tabs (folder + the command that was running, shown as a hint)
• apps — electron/GUI apps (telegram, rustdesk, editors…)
• background — manually-started node/python servers (NOT systemd services)
• other — uncertain classification; not auto-restored, shown for review only

Configuration

• Don't restore something: add its comm to the INFRA set in scan.js.
• Change the interval: OnUnitActiveSec in systemd/session-keeper.timer.
• History (last 30 snapshots): ~/.local/share/session-keeper/history/

Safety

• Never kills anything — it only launches, and skips what is already running.
• Atomic writes — a partial snapshot never survives a power cut; the last good snapshot is always intact.
• A terminal's last command is printed as a hint, not re-run automatically.

Roadmap

• Support more terminals (kitty, alacritty, GNOME Terminal, konsole)
• Optional auto-run of background servers on restore
• Per-item include/ignore lists
• Optional window-geometry restore on X11 sessions (where Wayland's limits don't apply)

Uninstall

bash uninstall.sh

License

MIT