tmux-resurrect is not actually saving your sessions; it’s a bit of a misnomer.
Let’s see it in action. You’re in tmux, have a few windows open, maybe split panes, running some processes. You want to save this state.
# Start tmux
tmux
# In tmux, create a few windows and panes
tmux new-window
tmux split-window -h
tmux select-pane -t 1
tmux split-window -v
tmux select-window -t 0
tmux attach-session
Now, imagine you have to reboot your machine, or your SSH connection drops unexpectedly. You want to get back to exactly where you were. This is where tmux-resurrect comes in.
# Install tmux-resurrect if you haven't already
# For example, using Homebrew on macOS
brew install tmux-resurrect
# Or clone it into your tmux plugin manager directory
git clone https://github.com/tmux-plugins/tmux-resurrect.git ~/.tmux/plugins/tmux-resurrect
You’ll need to configure your .tmux.conf to load the plugin. Add these lines:
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-resurrect'
# Initialize TMUX plugin manager (keep this line at the very bottom of tmux.conf)
run '~/.tmux/plugins/tpm/tpm'
After adding these, restart your tmux server (close all tmux sessions and start a new one) and press Prefix + I (that’s usually Ctrl+b followed by I) to install the plugin.
Now, to save your current session state, you’ll use Prefix + S (that’s Ctrl+b then S). tmux-resurrect will save the layout, window names, active panes, and even the commands running in your panes (if they haven’t exited).
After a reboot or a disconnect, when you start tmux again, tmux-resurrect will automatically try to restore your last saved session. If it doesn’t, you can manually trigger a restore with Prefix + R (Ctrl+b then R).
The magic is in how it serializes the state. It hooks into tmux’s internal commands to capture the current session configuration. For each window, it records its name, its active pane, and the pane structure (splits). Critically, for each pane, it tries to determine the current working directory and, if possible, the command that was running. This isn’t a full process snapshot; it’s more like saving the ps aux output and the pwd for each pane.
When restoring, it recreates the windows and panes with the saved layout. Then, for each pane, it cds into the saved directory and attempts to re-run the command it detected. This is why it’s so good at restoring development environments – it gets you back to the right place with your code editor or build process ready to go.
What most people don’t realize is that tmux-resurrect has a companion plugin, tmux-continuum, which can automatically save your session periodically or on tmux exit. This provides an even more robust safety net against unexpected shutdowns. You configure it similarly in your .tmux.conf:
set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @continuum-restore 'on' # Automatically restore session on startup
set -g @continuum-save-on-exit 'on' # Automatically save session when exiting tmux
With continuum-restore set to 'on', every time you start tmux, it will attempt to restore your last saved state, effectively making tmux-resurrect a background process.
The next step is understanding how to customize what tmux-resurrect saves and restores, especially when dealing with complex application states.