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-panestypes 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 labDrill 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/tpExpected:
✔ 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:
tmistmux -L lab -f ~/term-lab/tmux.conf. So the script always hits the lab server.-dcreates sessions and windows without jumping there. The switch happens only at the end.=projektmeans “exactly this name”. Without=, tmux also matches prefixes likeproj. In zsh you have to quote"=projekt", otherwise the shell looks for a programprojekt(Day 5,=ls).- Inside tmux (
$TMUXset),switch-clientswitches; outside,attachattaches.
Try it out:
tp ~/term-lab/projekt
tmux list-windows -F '#{window_index}:#{window_name} panes=#{window_panes}'
tmux lsExpected (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.confNew 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. Arebootin 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 fExpected (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 -2Expected (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-bootstarts 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=colour24Now 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.confIn 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
fiThen:
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 -2Expected (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-paneson 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
tpbelong in the dotfiles repo (Day 13). If you want more, look atsesh,tmuxinatororsmug. 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.