Learn Tmux - Persistence, Session Restore & Data Management

#Introduction

In episode 12 we covered options and environment management — how to read and change tmux behavior via set-option, show-options, set-environment, and update-environment. All those settings make tmux comfortable, but they leave one weak point: once the tmux server dies — whether from a machine reboot, a crash, or a permanently dropped SSH connection — all sessions, windows, panes, and running commands vanish with it.

In this episode we close that weak point with persistence: saving session state to disk and restoring it. We use two flagship plugins of the ecosystem — tmux-resurrect and tmux-continuum — then move on to data management: saving scrollback with capture-pane, logging windows with pipe-pane, and archiving sessions that have served their purpose. We install the plugins via TPM; a full deep-dive of the plugin ecosystem comes in episode 16.

#Why Persistence is a Need, Not a Luxury

There's one moment almost every engineer has felt: you're monitoring a database migration or a long build process, then the machine restarts for a kernel update, and all sessions — along with the mental context you were holding — vanish in an instant. tmux does save you from a dropped SSH connection, but the tmux server itself lives on the same machine. Once the machine dies, everything dies.

Persistence answers a deeper question: is your work context yours, or the machine's? With save/restore, your work context — which sessions are open, which windows in each session, pane layouts, active directories, even running commands — becomes an artifact that can be saved and reloaded. The analogy is exactly save/load in a game: without persistence, every reboot is "game over" and you start from the main menu; with persistence, you continue exactly from the last point.

#tmux-resurrect: Manual Save and Restore

tmux-resurrect is a plugin that saves the entire tmux session structure to a single text file in ~/.tmux/resurrect/ and can load it back. What's saved: sessions with names, windows, panes, layout, working directories, main environment, and — with extra configuration — the list of commands running in each pane.

#Installing via TPM

Resurrect is distributed through TPM. Add the following plugin declarations to ~/.tmux.conf, then bootstrap TPM on the last line:

set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-resurrect'
 
run '~/.tmux/plugins/tpm/tpm'

After that, reload with tmux source-file ~/.tmux.conf, then press prefix + I to install the plugins. TPM will clone tmux-resurrect into ~/.tmux/plugins/ and load it.

#prefix + Ctrl+s to Save

Once installed, save session state any time with prefix + Ctrl+s. No confirmation on screen except a brief status bar message; the process is fast because the state file is stored as plain text.

#prefix + Ctrl+r to Restore

To load the state back, press prefix + Ctrl+r. tmux will rebuild sessions, windows, panes, and layouts exactly as saved. This key combination is the main reason many engineers add resurrect on day one of their setup — because restore works on the same machine and different machines alike.

#Controlling What Gets Saved

Resurrect by default saves the session structure without scrollback contents. The two most commonly changed options:

set -g @resurrect-capture-pane-contents 'on'
set -g @resurrect-processes 'nvim "~" vim "~" bash "~"'
set -g @resurrect-strategy-nvim 'session'

The first line also saves the visible pane contents so the visual context isn't lost. The second line determines which programs get restored as processes — a list containing nvim, vim, and bash means panes running those programs will be reopened with the same program. The third line uses the session strategy for Neovim so the editor session is restored too. Remember: only programs on this list get restored; the rest open as an empty shell.

#tmux-continuum: Autosave and Auto-restore

tmux-resurrect leaves the save initiative to you — and initiative is often forgotten. tmux-continuum completes it with automation: it saves state periodically and restores it automatically when a new tmux is started. The combination is like autosave in an editor: you don't need to remember to press save, because the machine records progress routinely.

set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @continuum-save-interval '15'
set -g @continuum-restore 'on'
set -g @continuum-boot 'on'

The first line registers the plugin. The second makes an automatic save every 15 minutes. The third enables automatic restore: when a new tmux server starts and there are no sessions yet, continuum calls the resurrect restore. The fourth enables restoration on system boot — this requires tmux to run as a service (e.g. via systemd) so it can trigger the restore before you attach.

With these three options, the ideal flow becomes: the machine reboots, you open a terminal and run tmux, and without pressing a single key, all sessions return as before the reboot. The fundamental difference from tmux-resurrect alone: you're no longer part of a chain that can break because you forgot.

#Persistence Limitations: What Isn't Saved

Being honest about limitations keeps you safe from an illusion of security. Resurrect doesn't save the clipboard, tmux buffers, or scrollback contents — unless the @resurrect-capture-pane-contents option is enabled, and even then only the visible screen contents, not the whole history. Shell history is also not restored by default for security, because loading history without context could accidentally execute dangerous commands.

A healthy real-world approach: persistence for structure and programs, then data management for content that truly must be saved. The next section covers tmux tools for explicitly capturing that data.

#Saving Scrollback with capture-pane

capture-pane is the command to take a pane's contents — either the visible screen or the whole history — and print it to stdout. This is the fastest way to "rescue" running output before a pane is closed:

tmux capture-pane -p -S - > build.log
tmux capture-pane -p -S -100 -J > tail-100.log

The first line saves the entire history of the active pane (-S - means starting from the first line) to a file. The second line only takes the last 100 lines (-S -100) and joins wrapped lines with -J so the result is easy to read. For a specific pane, add a target: tmux capture-pane -p -t dev:0.1 -S - > out.txt.

#Logging Windows with pipe-pane

pipe-pane does something more alive: it forwards all pane output to an external command in real-time — ideal for monitoring logs to a file without touching the screen contents. The -o flag makes it act as a toggle: run it once to start, once more to stop.

tmux pipe-pane -o 'cat > /tmp/app.log'
tmux pipe-pane -o -t dev:1 'cat >> /tmp/api.log'
tmux pipe-pane -t dev:1

The first command starts logging the active pane to app.log. The second appends the dev:1 pane's log to api.log in append mode. The third command, without -o and without a command, stops that pane's logging pipeline. Because logging runs behind the scenes, the pane stays fully usable for normal work.

#Code-group: Capturing Data from a Pane

tmux capture-pane -p -S - > full.log
tmux capture-pane -p -S -100 -J > last-100.log
tmux capture-pane -p -t dev:0.1 -S - > specific-pane.log

tmux pipe-pane -o 'cat > /tmp/app.log'
tmux pipe-pane -o -t dev:1 'cat >> /tmp/api.log'
tmux pipe-pane -t dev:1

When to use which? capture-pane for a one-off snapshot — capturing an error output to report, saving results before closing a pane. pipe-pane for continuous recording — recording a debug session, monitoring an application log to a file that can be tail-ed from outside tmux.

#Archiving Old Sessions

Over time, sessions pile up. Instead of immediately killing an unused session, archive it first: rename with a date marker, move still-useful windows, then kill the rest. An archive flow commonly used by operations teams:

tmux rename-session -t deploy deploy-2026-08-02
tmux move-window -s deploy-2026-08-02:0 -t infra:5
tmux kill-session -t deploy-2026-08-02

rename-session gives a date label so archived sessions are easy to find via tmux list-sessions. move-window moves still-valuable windows to another session. kill-session is only run after the windows you need are secured. This pattern keeps list-sessions short without discarding data hastily.

#Common Pitfalls

1. Installing resurrect/continuum but forgetting to reload the config. After adding plugin declarations, run tmux source-file ~/.tmux.conf then prefix + I. Without a reload, TPM won't recognize the new plugin.

2. Relying on prefix + Ctrl+s for saving when only continuum autosave is active. Continuum saves periodically, but the first interval may not have been reached when the machine dies. For important moments, get in the habit of saving manually right before taking a big risk.

3. Putting dangerous programs in @resurrect-processes. Restore will re-run the programs on the list automatically. Destructive commands like rm -rf or automatic deploys shouldn't be on this list.

4. Using pipe-pane to a file in a directory that gets deployed. Ever-growing logs can bloat a repo or workspace. Point logs to /tmp or a clearly temporary directory.

5. Expecting restore to bring back scrollback without enabling capture. The default resurrect doesn't save pane history. If visual context matters, enable @resurrect-capture-pane-contents 'on' from the start — enabling it later doesn't restore already-passed data.

6. Killing sessions without archiving. kill-session removes windows that others might still need. If a session is used by a team, get in the habit of renaming with a date and moving still-living windows before cleaning up.

#Conclusion

This episode turned tmux from merely a "terminal that survives" into a "workspace that can be restored". You can now save the entire state with tmux-resurrect via prefix + Ctrl+s and load it with prefix + Ctrl+r, automate both with tmux-continuum (autosave every 15 minutes plus automatic restore), understand persistence's limitations, and manage data explicitly: scrollback snapshots with capture-pane, real-time output recording with pipe-pane, and orderly session archiving.

Key points to take away:

• tmux-resurrect saves the session structure; tmux-continuum makes save and restore run automatically.
• Persistence saves structure and programs, not scrollback contents — unless explicitly enabled.
• capture-pane for one-off snapshots; pipe-pane for continuous logging.
• Archive before killing: rename, move useful windows, then kill.

This save/restore ability is most valuable when triggered from inside a script — rebuilding a workspace without a single manual keystroke. In episode 14 we'll cover scripting, automation, and the command line — non-interactive commands like new -d and send-keys, declarative layouts with tmuxp and tmuxinator, and using the tmux CLI as an automation foundation. See you in episode 14!