Resurrecting tmux sessions after restart

Originally published on peateasea.de.

Cover image credits: Omah Obah Studio and Halloween Vectors by Vecteezy

Have you ever wished your tmux sessions could magically spring back to life after having had to restart your computer? With tmux-resurrect, they can.

Rebooting. It’s something that can’t always be avoided. If you’re like me and you usually have several tmux sessions open–each pertaining to a particular topic–it can be a hassle rebuilding everything after a restart. Fortunately, there’s a tmux plugin which can get you most of the way back to where you left off. Its name is tmux-resurrect and, as the name suggests, it resurrects your tmux environment.

Manage those plugins

Before we can use plugins, we have to install them. To install plugins, we use the tmux plugin manager (tpm), which we need to install first. Fortunately, the installation is rather easy; we simply clone the tpm repository into the ~/.tmux/plugins directory:

$ git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

Before we can use tpm, we have to add it to our ~/.tmux.conf configuration:

# List of plugins
set -g @plugin 'tmux-plugins/tpm'

This implies that the plugin manager is itself a plugin, which is interestingly recursive.

To ensure that tpm is set up and running properly, add the following initialisation code as the last line of your ~/.tmux.conf:

# Initialize TMUX plugin manager (keep this line at the very bottom of tmux.conf)
run '~/.tmux/plugins/tpm/tpm'

Now that tpm is installed, we can start adding plugins.

If you’re interested in what plugins are available, there’s a nice list of tmux plugins on GitHub.

Getting ready for resurrection

The plugin we’re interested in here is tmux-resurrect which will allow us to restore sessions after a restart.

To install the plugin, add it to the list of plugins in your ~/.tmux.conf file:

set -g @plugin 'tmux-plugins/tmux-resurrect'

Put the above line after the entry for tpm. In other words, the plugins section of the ~/.tmux.conf should now look like:

# List of plugins
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-resurrect'

We haven’t actually installed the plugin yet. However, due to the config file addition, we’re now able to.

To install the plugin, start tmux (if you haven’t already) by opening a terminal and entering tmux new, and then enter the key combination prefix I (I for install). In the default tmux configuration, prefix is Ctrl-b, hence in that case you’ll run the installation by entering first Ctrl-b followed by I. Since one of the first things people do when setting up tmux is to map the default prefix from Ctrl-b to Ctrl-a, your key combination is most likely to be Ctrl-a followed by I. For the rest of the text, I’m going to assume that the prefix is Ctrl-a.

A few seconds after entering Ctrl-a I you will see this message:

TMUX environment reloaded.
Done, press ENTER to continue.

This means that the plugin has been installed, so hit Enter to remove this text and continue.

Resurrecting a dead tmux session

Let’s see if everything worked as we expected. Since one of the cool things tmux-resurrect does is to resurrect running vim sessions, let’s create a quick “hello world” example Markdown file, open it in vim, and leave it running.

$ echo '# Hollow whirled' > hello.md
$ echo '## Visualise whirled peas' >> hello.md
$ vim hello.md

To save the state, enter Ctrl-a followed by Ctrl-s (i.e. save). After entering this key combination, you should see the text

Tmux environment saved!

at the bottom of your tmux window.

Nice! It looks like the session has been saved. Now we need to test if we can restore the session we just saved. Our expectation is that when resurrecting our session, we see the file hello.md open within vim.

If you don’t want to test resurrecting a dead tmux session by restarting your computer, you can simply kill the tmux server process to emulate the same process. To run this test, open a new terminal (not within tmux!) and kill your running tmux server process. The commands will look something like this:

$ ps -ef | grep 'tmux new'
# select PID of tmux server process (will probably have a parent process with PID 1)
$ kill <PID>

Back in your terminal where tmux was running (and where you previously had started tmux via tmux new), you will see something like this:

$ tmux new
[server exited]

To resurrect the session, start tmux again:

$ tmux new

and then enter Ctrl-a followed by Ctrl-r (i.e. restore). You should very briefly see the text

Tmux restore complete!

at the bottom left-hand corner of the screen. Then you will see vim start again and load the hello.md file we had open earlier. Cool!

Automated resurrection

Now that we’ve got resurrection working properly, we’d like to avoid having to think of entering Ctrl-a Ctrl-s each time we want to save our running tmux session. To periodically and automatically save the tmux session state, we can use the tmux-continuum plugin.

To install the plugin, add it to the ~/.tmux.conf configuration after the entry for tmux-resurrection (tmux-continuum needs tmux-resurrection to be installed as a prerequisite, so it’s good we’ve already installed that!). Our plugin configuration now looks like this:

# List of plugins
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'

Complete the installation by entering Ctrl-a followed by I within a running tmux session. Again you will see this text:

TMUX environment reloaded.
Done, press ENTER to continue.

whereupon you can hit Enter to continue.

tmux-continuum will now automatically save the tmux environment every 15 minutes.

If you want the tmux environment to be resurrected automatically when tmux starts, add this option to your ~/.tmux.conf after the list of plugins:

set -g @continuum-restore 'on'

That’s all folks!

And that’s it! There are more options for tmux-resurrect that you could use. For instance, it’s possible to restore pane contents or restore various processes so that they’re running again after restarting tmux.

There’s much more for you to try out to enhance your tmux experience!