Skip to content
Hands-on IT IT Drills

Day 9: tmux II – projects, popups, persistence

Goal: Build project sessions by script in seconds, work with layouts, synchronized panes and popups, rescue sessions across restarts and use tmux cleanly over SSH. · Duration: approx. 90 min · Prerequisite: Day 8

Briefing

  • Senior workflow: one session per project, always built the same way. One command (tp) jumps there or builds it.
  • Layouts arrange panes at the push of a button, synchronize-panes types into all panes at once.
  • Popups (display-popup) briefly lay tools like lazygit or a project picker over everything.
  • tmux-resurrect saves sessions to disk, tmux-continuum does it automatically.
  • On servers, tmux runs there, not locally: ssh -t host tmux new -A -s main.
tp ~/term-lab/projekt
 └─ Session "projekt"
     ├─ 1:edit   $EDITOR .
     ├─ 2:run    ┌───────────────┬─────────┐   main-vertical
     │           │ Shell         │ Shell   │
     │           └───────────────┴─────────┘
     └─ 3:git    git status -sb

You append all extensions to ~/term-lab/tmux.conf from Day 8. The finished file is at $BUCH/tmux/tmux.conf. Start the lab session from the lab shell as usual:

cd ~/term-lab/projekt
tl new -A -s lab

Drill 1: Layouts

Open a new window (⌃a c) and split it three times (⌃a |, ⌃a -, ⌃a -). Then press ⌃a Space several times: tmux cycles through the five basic layouts.

Key Layout What for
⌃a ⌥1 even-horizontal panes side by side, equal width
⌃a ⌥2 even-vertical panes stacked
⌃a ⌥3 main-horizontal large pane on top, the rest below
⌃a ⌥4 main-vertical large pane on the left (editor), the rest on the right
⌃a ⌥5 tiled grid, e.g. for four servers
⌃a Space next layout cycle through

The ⌥ keys need Option as Meta (Day 1). More convenient: a dedicated key for the grid and a wider main pane:

cat >> ~/term-lab/tmux.conf <<'EOF'

# ============================ Day 9 ==========================================
# --- Layouts and synchronize-panes -------------------------------------------
set -g main-pane-width 60%
bind = select-layout tiled
EOF
tmux source-file ~/term-lab/tmux.conf
tmux select-layout main-vertical
tmux list-panes -F '#{pane_index} #{pane_width}x#{pane_height}'

Expected (sizes depend on the terminal):

1 71x39
2 48x13
3 48x12
4 48x12

A layout can also be saved and restored later:

L=$(tmux display -p '#{window_layout}')
tmux select-layout tiled
tmux select-layout "$L"

Current tmux versions understand percentages for main-pane-width. Very old ones want columns (120).

Save your progress? Sign up for free

Drill 2: Project session by script

Every project gets the same session: editor, two shells, Git. The tp script creates it if it’s missing and otherwise just jumps there. It’s ready-made in the code folder:

cp $BUCH/tmux/tp ~/term-lab/bin/tp && chmod +x ~/term-lab/bin/tp
shellcheck ~/term-lab/bin/tp && echo "✔ shellcheck"
sed -n '/^if ! tm has-session/,/^fi/p' ~/term-lab/bin/tp

Expected:

✔ shellcheck
if ! tm has-session -t "=$name" 2>/dev/null; then
  [[ -n $dir ]] || { echo "tp: '$target' ist weder Session noch Ordner" >&2; exit 1; }
  tm new-session -d -s "$name" -c "$dir" -n edit
  tm send-keys -t "=$name:edit" "${EDITOR:-vi} ." Enter
  tm new-window -d -t "=$name:" -n run -c "$dir"
  tm split-window -d -h -t "=$name:run" -c "$dir"
  tm select-layout -t "=$name:run" main-vertical
  tm new-window -d -t "=$name:" -n git -c "$dir"
  tm send-keys -t "=$name:git" "git status -sb" Enter
fi

The building blocks:

  • tm is tmux -L lab -f ~/term-lab/tmux.conf. So the script always hits the lab server.
  • -d creates sessions and windows without jumping there. The switch happens only at the end.
  • =projekt means “exactly this name”. Without =, tmux also matches prefixes like proj. In zsh you have to quote "=projekt", otherwise the shell looks for a program projekt (Day 5, =ls).
  • Inside tmux ($TMUX set), switch-client switches; outside, attach attaches.

Try it out:

tp ~/term-lab/projekt
tmux list-windows -F '#{window_index}:#{window_name} panes=#{window_panes}'
tmux ls

Expected (shortened):

1:edit panes=1
2:run panes=2
3:git panes=1
lab: 5 windows (created Sat Oct 10 08:51:12 2026)
projekt: 3 windows (created Sat Oct 10 08:55:03 2026) (attached)

A second tp ~/term-lab/projekt doesn’t rebuild anything, it just jumps there. ⌃a ( takes you back to the lab session.

Save your progress? Sign up for free

Drill 3: synchronize-panes – one command, all panes

A classic in operations: four SSH sessions, the same command everywhere. In the lab you simulate that with three local panes:

cat >> ~/term-lab/tmux.conf <<'EOF'
bind S setw synchronize-panes \; display "Sync: #{?synchronize-panes,an,aus}"
setw -g window-status-current-format \
  " #I:#W#{?window_zoomed_flag, [Z],}#{?synchronize-panes, [SYNC],} "
EOF
tmux source-file ~/term-lab/tmux.conf

New window (⌃a c), ⌃a |, ⌃a -, then ⌃a = for the grid. Now ⌃a S and type once:

clear; echo "pane $TMUX_PANE"

Expected (shortened):

pane %17                          │pane %18
[lab] projekt %                   │[lab] projekt %
──────────────────────────────────┴──────────────────────────────────
pane %19
[lab] projekt %
 lab   1:zsh   2:logs   3:zsh   4:zsh   5:zsh [SYNC]              08:55

All three panes got the command, each with its own pane ID. ⌃a S turns it off again (Sync: aus – “off”).

Warning: Never forget to turn sync off again. That’s what the [SYNC] in the status line is for. A reboot in a synchronized window hits every server in it.

Save your progress? Sign up for free

Drill 4: Popups – tools on top of everything

display-popup opens a floating window. -E closes it as soon as the command ends. Three popups you need every day:

cat >> ~/term-lab/tmux.conf <<'EOF'

# --- Popups --------------------------------------------------------------------
bind f display-popup -E -w 70% -h 60% "$LAB/bin/tp"
bind g display-popup -E -w 90% -h 90% -d "#{pane_current_path}" lazygit
bind t display-popup -E -w 80% -h 60% -d "#{pane_current_path}"
EOF
tmux source-file ~/term-lab/tmux.conf
tmux list-keys -T prefix f

Expected (shortened):

bind-key  -T prefix f display-popup -E -h "60%" -w "70%" /Users/du/term-lab/bin/tp

tmux substitutes $LAB when loading. You need the full path because the popup doesn’t start an interactive shell with your PATH.

⌃a t opens a throwaway shell in the current path. Type pwd, then exit:

           ┌─────────────────────────────────────────────────────────┐
           │[lab] projekt % pwd                                      │
           │/Users/du/term-lab/projekt                               │
           │[lab] projekt %                                          │

⌃a g lays lazygit over the whole window, q closes it. That replaces the window solution from the Day 8 challenge. Delete the bind g new-window … line there, otherwise the binding that comes later in the file wins.

⌃a f is a project picker in the style of “sesh”: tp without arguments lists running sessions and all folders from your zoxide database (Day 6). Type projekt$:

┌──────────────────────────────────────────────────────────────────────┐
│projekt> projekt$                 ╭───────────────────────────────╮   │
│  1/5 ─────────────────────────── │ cmd                           │   │
│▌ /Users/du/term-lab/projekt      │ config                        │   │
│                                  │ deploy                        │   │

Enter switches to the projekt session, creates it if necessary, and the popup closes. The preview shows the contents for folders and the screen of the active pane for sessions.

Save your progress? Sign up for free

Drill 5: Persistence with tmux-resurrect and tmux-continuum

A tmux server doesn’t survive a logout or a restart. tmux-resurrect writes sessions, windows, paths, layouts and running programs (nvim, tail, less …) to a file. tmux-continuum saves every 15 minutes and restores when the server starts.

Normally the plugin manager tpm installs the plugins. But tpm only looks for @plugin lines in ~/.tmux.conf or ~/.config/tmux/tmux.conf. It doesn’t see our lab file passed via -f. That’s why in the lab you clone them yourself and load the plugins with run:

mkdir -p ~/term-lab/tmux/plugins
for p in tmux-resurrect tmux-continuum; do
  git clone -q --depth 1 https://github.com/tmux-plugins/$p \
    ~/term-lab/tmux/plugins/$p
done
cat >> ~/term-lab/tmux.conf <<'EOF'

# --- Persistence: tmux-resurrect + tmux-continuum (without tpm, see Day 9) -----
set -g @resurrect-dir "$LAB/tmux/resurrect"
set -g @resurrect-capture-pane-contents 'on'
set -g @continuum-save-interval '15'
set -g @continuum-restore 'on'
if "test -d $LAB/tmux/plugins/tmux-resurrect" \
  "run '$LAB/tmux/plugins/tmux-resurrect/resurrect.tmux'"
if "test -d $LAB/tmux/plugins/tmux-continuum" \
  "run '$LAB/tmux/plugins/tmux-continuum/continuum.tmux'"
EOF
tmux source-file ~/term-lab/tmux.conf
tmux list-keys -T prefix | rg -o 'C-[rs] .*scripts/\S+'

Expected:

C-r     run-shell /Users/du/term-lab/tmux/plugins/tmux-resurrect/scripts/restore.sh
C-s     run-shell /Users/du/term-lab/tmux/plugins/tmux-resurrect/scripts/save.sh

@resurrect-dir is mandatory in the lab. Without that line, resurrect writes to ~/.local/share/tmux/resurrect and mixes with a real setup.

The stress test. ⌃a ⌃s saves (Saving... briefly appears at the bottom). Then ⌃a d, and in the lab shell outside tmux, kill the server and start it again:

tl kill-server
tl new -d -s tmp
sleep 5; tl ls
tl list-windows -t lab \
  -F '#{window_index}:#{window_name} #{pane_current_command}' | head -2

Expected (shortened):

lab: 7 windows (created Sat Oct 10 08:59:38 2026)
tmp: 1 windows (created Sat Oct 10 08:59:40 2026)
1:zsh zsh
2:logs tail

continuum automatically brought back the lab session at startup, including tail -f in the logs window. By hand: ⌃a ⌃r. The backups are text files in ~/term-lab/tmux/resurrect/; last points to the newest one.

Warning: continuum only saves automatically when exactly one tmux server is running. If your normal tmux runs alongside the lab, auto-save stays off (manual ⌃a ⌃s always works). @continuum-boot starts tmux at login via launchd. Leave that out in the lab.

For your real ~/.tmux.conf (Day 13), tpm is the standard. It looks like this:

set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @continuum-restore 'on'
run '~/.tmux/plugins/tpm/tpm'      # always the last line

Installation there: git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm, then ⌃a I (capital i) in tmux.

Save your progress? Sign up for free

Drill 6: tmux over SSH and nested

On a server, tmux runs on the server. Connection gone, work stays:

ssh -t jump01 'tmux new -A -s main'

-t forces a terminal, new -A attaches to main or creates it. To make it permanent, put RequestTTY yes and RemoteCommand tmux new -A -s main in ~/.ssh/config (Day 12).

If that runs inside your local tmux, you have tmux in tmux. Which tmux gets your keys? You simulate that locally with a second server playing “remote”:

tmux -L lab-remote -f /dev/null new -s remote \; set -g prefix C-a \; \
  set -g status-style bg=colour24

Now you have two status lines: blue at the bottom inside ([remote]), orange outside (lab).

  • ⌃a c goes to the outer tmux. It catches the prefix first.
  • ⌃a ⌃a c goes to the inner one: the first ⌃a sends a ⌃a through via send-prefix.
  • If the server has the default prefix ⌃b, you simply type ⌃b c there.

More convenient for long remote sessions: F12 mutes the outer tmux, and all keys go inside. F12 again switches back.

cat >> ~/term-lab/tmux.conf <<'EOF'

# --- Nested tmux (SSH): F12 mutes the outer tmux ---------------------------------
bind -T root F12 set prefix None \; set key-table off \; \
  set status-style "bg=colour238,fg=colour244" \; refresh-client -S
bind -T off F12 set -u prefix \; set -u key-table \; set -u status-style \; \
  refresh-client -S
EOF
tmux source-file ~/term-lab/tmux.conf

In the inner tmux: F12, then ⌃a c. The new window is created inside, the outer status line is gray. F12 makes it orange again. Clean up: type exit in the inner tmux until it’s gone, or tmux -L lab-remote kill-server.

Save your progress? Sign up for free

Shortcut table

Key / command Effect Mnemonic
⌃a Space next layout Space = page forward
⌃a ⌥1 … ⌥5 pick layout directly 4 = editor on the left
⌃a = grid (tiled) “=” means equal size
⌃a S synchronize-panes on/off Sync
⌃a f project picker (tp) in a popup find project
⌃a g lazygit in a popup git
⌃a t throwaway shell in a popup terminal
⌃a ⌃s / ⌃a ⌃r save / restore sessions save, restore
⌃a ⌃a prefix to the inner tmux double = pass through
F12 mute/unmute the outer tmux F12 = far, far away
tp <dir> create project session or jump there tmux project
ssh -t host 'tmux new -A -s main' tmux on the server Attach or create

Checkpoint

In the lab shell, with the projekt session from Drill 2 running:

c() { eval "$2" >/dev/null 2>&1 && echo "✔ $1" || echo "✘ $1"; }
c "tp im PATH"        'whence tp && shellcheck $LAB/bin/tp'
c "Session projekt" 'tl has-session -t "=projekt"'
c "edit run git" 'tl list-windows -t "=projekt" -F "#W" | xargs | rg -q "^edit run git"'
c "Raster-Taste ="    'tl list-keys -T prefix = | rg -q tiled'
c "Sync-Taste S"      'tl list-keys -T prefix S | rg -q synchronize-panes'
c "Popups f, g, t"    '(( $(tl list-keys -T prefix | rg -c display-popup) >= 3 ))'
c "resurrect im Lab"  '[[ $(tl show -gv @resurrect-dir) == */term-lab/tmux/resurrect ]]'
c "Sicherung da"      '[[ -e ~/term-lab/tmux/resurrect/last ]]'
c "F12 für Nesting"   'tl list-keys -T root F12 | rg -q key-table'

Expected: nine lines with ✔.

Challenge

Extend tp: if a project has a deploy/k8s folder, the session gets a fourth window k8s in that folder. In it, the lab kubeconfig from Day 7 is set and the current context is shown.

Hint: The new block goes into the if ! tm has-session …, right before its fi. Test with tl kill-session -t projekt and a new tp.

Solution

In ~/term-lab/bin/tp, insert after the line tm send-keys -t "=$name:git" …:

  if [[ -d $dir/deploy/k8s ]]; then
    tm new-window -d -t "=$name:" -n k8s -c "$dir/deploy/k8s"
    tm send-keys -t "=$name:k8s" \
      "export KUBECONFIG=$LAB/kube/config; kubectl config current-context" Enter
  fi

Then:

shellcheck ~/term-lab/bin/tp && echo "✔ shellcheck"
tl kill-session -t projekt
tp ~/term-lab/projekt
tmux list-windows -F '#{window_index}:#{window_name}'
tmux capture-pane -p -t projekt:k8s | rg -v '^$' | tail -2

Expected (context depending on your state from Day 7):

✔ shellcheck
1:edit
2:run
3:git
4:k8s
lab-dev
[lab] k8s %

Save your progress? Sign up for free

Enterprise Note

  • Use synchronize-panes on production servers only with the four-eyes principle. For real fleets, this belongs in Ansible, Salt or a runbook tool, not in typed commands.
  • Shared jump hosts: one session per person (tmux new -A -s $USER), never attach to other people’s sessions. Pair deliberately via a shared socket with group permissions.
  • resurrect saves paths, commands and, with capture-pane-contents, screen contents too. Secrets can be in there. The directory doesn’t belong in backups without encryption and never in Git.
  • Project scripts like tp belong in the dotfiles repo (Day 13). If you want more, look at sesh, tmuxinator or smug. The principle stays the same.
  • On servers without your config, ⌃b applies. Practice both prefixes so you don’t hunt for the key in an emergency.