Session restore for Omarchy: saves the windows you have open and brings them back after a reboot, shutdown, logout or crash. An Omarchy shell plugin for Hyprland 0.55+.
Every window is restored on the workspace and monitor it was on. Floating windows keep their position and size. Pinned, fullscreen and grouped windows come back in that state, and a group keeps its tab order and the tab it showed. Terminals reopen in their last working directory, browsers keep their tabs, and web apps opened from a Chromium browser come back as their own windows. Saving is automatic, so there is no save step before you power off.
Python 3.9, standard library only. No compositor patches and no extra daemons.
Needs Omarchy 4 (Quattro) or newer.
omarchy plugin add https://github.com/asmyshlyaev177/omarchy-last-session.git --enableIt then saves a snapshot whenever a window opens, closes or moves, and restores it two seconds after the shell starts on your next login.
If the command ends with omarchy-shell is not responding, the plugin is installed but may be left disabled. Check omarchy plugin list and run omarchy plugin enable io.github.asmyshlyaev177.last-session.
Add the classes your own autostart already launches to exclude in ~/.config/omarchy/last-session.ini, which the plugin writes the first time it runs:
exclude = my-autostarted-app, another-classFind a window's class with hyprctl clients -j | jq '.[].class'. The change takes effect within a minute. The other keys are under Configuration below, with the menu entry that opens the file.
omarchy plugin update io.github.asmyshlyaev177.last-sessionomarchy plugin remove io.github.asmyshlyaev177.last-session
rm -r ~/.local/state/omarchy-last-session ~/.config/omarchy/last-session.iniWhatever you added by hand stays: the power menu actions, and the menu entry below, which hides itself while the plugin is gone.
Its own state directory, ~/.local/state/omarchy-last-session, its config file, ~/.config/omarchy/last-session.ini, written once with the defaults, and one file belonging to another app: before relaunching a Chromium-based browser it sets profile.exit_type to Normal in each profile's Preferences, because Chromium will not restore tabs after what it recorded as a crash. Nothing else in that file changes.
Omarchy closes every window, one at a time, about two seconds before it powers off. Most apps hold the shutdown themselves for as long as they need. A Chromium-based browser forgets each window that closes while another of its windows is still open, and VS Code remembers only the last window closed. Both keep every window when they are told to quit first, which is what the plugin's rows for the Omarchy menu do. Print them with:
~/.config/omarchy/plugins/io.github.asmyshlyaev177.last-session/bin/omarchy-last-session menuPaste what it prints inside the outer braces of ~/.config/omarchy/extensions/omarchy-menu.jsonc. If the file does not exist, create it with the rows between { and }. The menu reloads the file on save.
Each power row is a copy of Omarchy's own Logout, Reboot or Shutdown row, with the same icon and label, whose action runs the plugin's shutdown first. The guard in each action means the plugin being removed changes nothing: the row skips straight to powering off. Leave suspend and hibernate alone, they resume the live session. The remaining row opens the config file, as described under Open it from the Omarchy menu.
The plugin reopens windows. What is inside them comes from each app's own persistence:
| App | What comes back |
|---|---|
| Firefox, Zen, Brave, Chromium, Chrome, Edge | tabs, even after Omarchy killed them |
| sioyek, okular, zathura | the document, at the last page |
| Obsidian | the last open vaults |
| VS Code | its own windows and the folders open in them |
| Dolphin | open tabs, with Settings → Startup → "same locations as when closed" |
| kitty | its OS windows, tabs, splits and directories, with remote control on |
| a terminal | the shell's last directory, or a TUI (yazi, nvim, vim, btop, htop, ranger, lf) in its own |
Terminals supported out of the box: ghostty, kitty, foot, alacritty. Another is one line under [terminals] in the config file.
Turning kitty's remote control on is what lets it describe its tabs and splits:
allow_remote_control socket-only
listen_on unix:${XDG_RUNTIME_DIR}/kitty-{kitty_pid}Use a socket file as above, not an @ name: a sandboxed app can reach an @ socket but not this file.
- The exact tiling layout. Windows land on the right workspace and monitor and re-tile in saved left-to-right order. Floating windows are pixel-exact.
- Unsaved in-app state: scrollback, scroll positions, unsaved edits.
- An app that takes more than thirty seconds to show a window. It is left unplaced and named in the log.
- One window from an app that serves every window from one process and reopens none of them itself, such as LibreOffice or GIMP.
- Titles and floating geometry changed in the last minute before a crash. A clean shutdown loses neither.
- Same-class windows from one process are told apart by their titles, so two showing the same thing can end up in each other's places. Every pairing is logged.
Restore refuses to run when more than three windows are already open, so enabling the plugin mid-session reopens nothing. It also runs only once per Hyprland session, so a shell restart, such as the one omarchy update ends with, reopens nothing either. Running restore from a terminal still reopens the session.
The config file is ~/.config/omarchy/last-session.ini. The plugin writes it the first time it runs, with every default it ships with and a comment on each, so what is in force is what the file says, and the apps it treats specially are there to add to. A saved change takes effect within a minute, with no restart. A key left out keeps its default, a section left out keeps its whole table, and a value the plugin cannot use is reported in the journal and ignored.
[general]:
| Key | Meaning | Default |
|---|---|---|
exclude |
window classes never saved or restored, besides the shell's own | |
session_keeping |
apps that reopen their own windows: launched once per process, and sent SIGTERM by shutdown so they write their windows down first. Every browser under [chromium-browsers] is one too |
code, code-oss, code-insiders, codium |
single_instance |
apps launched once for all of their windows, because a second launch joins the first, but never signalled: a SIGTERM raises a save prompt | LibreOffice, gimp |
tui_programs |
programs relaunched inside their terminal | yazi, nvim, vim, btop, htop, ranger, lf |
shells |
what a terminal runs at its prompt; it reopens in that shell's directory | fish, zsh, bash, sh, nu |
state_dir |
where snapshots are kept | ~/.local/state/omarchy-last-session |
settle_delay |
seconds vanished windows stay unsaved | 10 |
save_interval |
seconds between saves when no window has opened, closed or moved | 60 |
sweep_timeout |
seconds restore waits for the windows it launched | 30 |
title_settle |
seconds restore waits for an app's windows to turn up and for their titles to stop changing, which is what tells a browser's windows apart | 5 |
max_preexisting_windows |
windows that may already be open before restore refuses to run | 3 |
Two tables, one row per window class:
| Section | Row | Ships with |
|---|---|---|
[terminals] |
class = binary, working-directory flag[, flag that runs a program] |
kitty, foot, Alacritty, ghostty |
[chromium-browsers] |
class = profile directory under ~/.config; each gets --restore-last-session and the clean-exit mark |
Brave, Chromium, Chrome, Edge |
Lists are comma separated. Quotes around a value are dropped, # after a value starts a comment, and a state_dir that is not absolute is taken from your home. Steam and AppImages need no entry: their command lines cannot be replayed, so each is relaunched through its .desktop entry.
The setup.config.last-session row that menu prints puts the file under Setup › Config › Last Session, where a search for "session" finds it. Its when guard hides the row while the plugin directory is gone. To add this row without the power rows, paste only its line. The same config command from a terminal opens the file in your editor too.
To skip the next restore without disabling the plugin:
touch ~/.local/state/omarchy-last-session/disabledSix commands, which work without the shell service. restore --login runs at login and daemon after it, and a plain restore reopens the session whenever you ask; save and shutdown are for your own scripts; config opens the config file in your editor; menu prints the rows for your menu file.
~/.config/omarchy/plugins/io.github.asmyshlyaev177.last-session/bin/omarchy-last-session save
~/.config/omarchy/plugins/io.github.asmyshlyaev177.last-session/bin/omarchy-last-session restoreEverything the plugin prints reaches the journal:
journalctl --user -t omarchy-shell -b | grep omarchy-last-session| Question | Where to look |
|---|---|
| What did restore bring back, and where did it put things? | last-restore.json, plus the log: each launch, every title a window showed until it was paired, and each pairing with its scores |
| What did the last shutdown save? | last-shutdown.json, written by shutdown only |
| Nothing came back | session.json. An empty window list means the desktop was empty for ten seconds before shutdown |
| A window did not come back | the log names it |
| A browser window did not come back, and the log says the browser reopened its others | the browser forgot it, because Omarchy closed it before the browser quit. The rows under Let apps save before the power goes prevent that |
The power menu shows system.shutdown with no icon, in place of Shutdown, or a power row looks different from Omarchy's own |
the rows in your menu file came from an older version of the plugin, or of Omarchy. Print them again with menu and replace the old ones, as under Let apps save before the power goes |
| Is the plugin running? | omarchy plugin list --json | jq '.[] | select(.id == "io.github.asmyshlyaev177.last-session")' |
All four files live in ~/.local/state/omarchy-last-session.
python3 -m unittest discover -s tests -v
uvx ruff check . && uvx ruff format --check .
uvx mypy==1.19.1 # strict type check, settings in pyproject.toml
uvx pyright==1.1.414 # the same with the checker Pylance runs
omarchy plugin validate .
tests/integration/run.sh # live, needs Podman or Docker and a DRM render node
OLS_VM=1 tests/integration/run.sh # live in a VM, needs /dev/kvm instead of a render node
tests/integration/run.sh -k two_monitors # one live testThe code is the omarchy_last_session package; bin/omarchy-last-session only starts it. docs/development_notes.md holds the notes for changing it.
| Module | What it holds |
|---|---|
config |
every knob, and the config file that sets some of them |
proc |
the /proc readers |
hypr |
hyprctl requests, the event socket, Lua quoting, monitor and window views |
relaunch |
recovery of a window's relaunch command |
chromium |
the clean-exit mark a Chromium-based browser needs before it restores its tabs |
kitty |
a kitty instance's tabs and splits, rendered as a session file |
session |
the snapshot file, the daemon's schedule, the graceful quit at shutdown |
restore |
the restore pass |
notification |
the toast shown while restore runs, sent and taken down through Omarchy's own commands |
cli |
the six commands |
The unit tests need no compositor: /proc and hyprctl are read through named functions the tests substitute. The live tests drive the plugin against a real Hyprland in a container, with stand-in apps for the shapes that break restore.
MIT