GitHub - hyoretsu/tmux-persist: Persists tmux sessions across system restarts.

Restore tmux environment after system restart.

tmux-persist is a maintained fork of the (abandoned) tmux-resurrect. It automatically saves and restores pane-contents and layout per session on every kill/detach/start.

Coming from tmux-resurrect? Upgrading is seamless: unset @persist-* options fall back to the old @resurrect-* names and directory (deprecated - rename when convenient), and your previously saved snapshot is migrated to the new per-session format automatically on first load.

Tmux is great, except when you have to restart the computer. You lose all the running programs, working directories, pane layouts etc. There are helpful management tools out there, but they require initial configuration and continuous updates as your workflow evolves or you start new projects.

tmux-persist saves all the little details from your tmux environment so it can be completely restored after a system restart (or when you feel like it). No configuration is required. You should feel like you never quit tmux.

It even (optionally) restores vim and neovim sessions!

Automatic saving and restoring already happens on its own (see below) - no extra plugin needed for that. For periodic saving on a fixed timer, independent of any attached client, see "Other goodies" below.

Screencast

Key bindings

• prefix + Ctrl-s - save the session you are currently attached to
• prefix + Ctrl-r - restore the session you are currently attached to

Each session is saved separately to its own files, so save and restore only ever touch the session you are in — restore never recreates or switches you to other sessions. To save/restore a specific session by name, run scripts/save.sh <session-name> / scripts/restore.sh <session-name>. To restore every saved session at once (e.g. after losing the whole tmux server), run scripts/restore.sh all - see restoring a previously saved environment.

Saving and restoring also happen automatically: sessions are saved on detach, disconnect and exit, and restored when a session is (re)created. See automatic saving and restoring. Disable with @persist-save-on-exit 'off' / @persist-auto-restore 'off'.

About

This plugin goes to great lengths to save and restore all the details from your tmux environment. Here's what's been taken care of:

• all sessions, windows, panes and their order
• current working directory for each pane
• exact pane layouts within windows (even when zoomed)
• active and alternative session
• active and alternative window for each session
• windows with focus
• active pane for each window
• "grouped sessions" (useful feature when using tmux with multiple monitors)
• programs running within a pane! More details in the restoring programs doc.
• pane contents (the visual command history of each pane), saved separately per session and enabled by default. See restoring pane contents.

Optional:

• restoring vim and neovim sessions
• restoring AI agent CLI sessions (claude, codex, copilot, cursor-agent, agy, gemini, opencode)
• restoring a previously saved environment

Requirements / dependencies: tmux 1.9 or higher, bash.

Tested and working on Linux, OSX and Cygwin.

tmux-persist is idempotent! It will not try to restore panes or windows that already exist.
The single exception to this is when the session being restored has only 1 pane (e.g. a freshly created session). Only in this case will that single pane be overwritten.

Installation with Tmux Plugin Manager (recommended)

Add plugin to the list of TPM plugins in .tmux.conf:

set -g @plugin 'hyoretsu/tmux-persist'

Hit prefix + I to fetch the plugin and source it. You should now be able to use the plugin.

Manual Installation

Clone the repo:

$ git clone https://github.com/hyoretsu/tmux-persist ~/clone/path

Add this line to the bottom of .tmux.conf:

run-shell ~/clone/path/persist.tmux

Reload TMUX environment with: $ tmux source-file ~/.tmux.conf. You should now be able to use the plugin.

Docs

• Guide for migrating from tmuxinator

Configuration

• Full options reference — every option, its default and what it does, in one place.
• Changing the default key bindings.
• Setting up hooks on save & restore.
• Only a conservative list of programs is restored by default:
  vi vim nvim emacs man less more tail top htop irssi weechat mutt.
  Restoring programs doc explains how to restore additional programs.
• Change a directory where tmux-persist saves tmux environment (@persist-dir).
• Automatic saving and restoring on detach, disconnect, exit and session creation (@persist-save-on-exit, @persist-auto-restore).
• Snapshots older than 7 days are erased automatically. Change the window with set -g @persist-delete-backup-after '<days>'. When all of a session's snapshots expire, the session is forgotten entirely (its last pointer and pane contents go too).
• Optionally cap how many snapshots each session keeps with set -g @persist-max-snapshots '<n>' (default 0 = unlimited). Extras beyond the newest n are erased regardless of age.
• A save whose content (layout + pane contents) is identical to the session's latest snapshot writes no new file — the existing snapshot's timestamp is refreshed instead, so frequent auto-saves on detach don't pile up duplicates. Disable with set -g @persist-skip-unchanged 'off' to always write a new snapshot.
• Each snapshot bundles its layout and pane contents in one file by default. Store them apart with set -g @persist-snapshot-format 'separate'. See restoring pane contents for what a snapshot contains.

Optional features

• Restoring vim and neovim sessions is nice if you're a vim/neovim user.
• Restoring AI agent CLI sessions resumes the most recent conversation per pane for claude, codex, copilot, cursor-agent, agy (Antigravity), gemini and opencode, enabled by default.
• Restoring pane contents is enabled by default; this doc explains how to tune or disable it.

Other goodies

• tmux-copycat - a plugin for regex searches in tmux and fast match selection
• tmux-yank - enables copying highlighted text to system clipboard
• tmux-open - a plugin for quickly opening highlighted file or a url
• tmux-continuum - automatic restoring and continuous saving of tmux env; both work with tmux-persist via small compatibility wrappers, see tmux-continuum compatibility
• tmux-persist-autosave - save-only supplement to continuum: crash-protects long-running background work (e.g. server-side scripts) even if no terminal is open; continuum requires an attached terminal

Reporting bugs and contributing

Both contributing and bug reports are welcome. Please check out contributing guidelines.

Credits

Bruno Sutic and the tmux-resurrect contributors - tmux-persist is a fork of their work.

Mislav Marohnić - the idea for the plugin came from his tmux-session script.

License

MIT