Stage 1 — Survival Kit

Stage 1 — Survival Kit

Install tmux, drill the ten commands you’ll use 80% of the time, and run the persistence demo. By the end of this page you’ll have the muscle memory to never lose a session to a network blip again.

Prefix key

This page uses Ctrl+a for the prefix — the iSu dev server standard. On a vanilla tmux setup the prefix is Ctrl+b; substitute it wherever you see Ctrl+a X. See the Introduction for how to check.

---

🎯 Goal

After this stage you will be able to:

• Install tmux on macOS and on Ubuntu (production-server-01).
• Create, list, attach to, and kill named sessions from the shell.
• Detach, split panes, and switch panes from inside a session.
• Verify whether you’re inside or outside tmux at a glance.

---

📋 Prerequisites

• A working terminal on macOS (iTerm2, Terminal.app, Ghostty, or Warp).
• SSH access to production-server-01 if you want to practise the remote workflow.
• About 30 minutes for the install + drill.

---

📦 Install tmux

macOS (local)

brew install tmux

If Homebrew isn’t installed yet, grab it from brew.sh first.

Verify the install:

tmux -V

You should see something like tmux 3.5a or higher.

Ubuntu / Debian (production-server-01)

sudo apt update
sudo apt install tmux

Same verification:

tmux -V

Working from iPad / Termius

If you’re using Termius on iPad, tmux is installed on the server, not on the iPad. Connect via SSH first, then run tmux there. Termius itself doesn’t need tmux — it’s just an SSH client.

---

🛠️ The ten commands

Five commands run from your regular shell — they create and manage sessions from the outside. Five commands run inside tmux — they need the prefix key.

From the shell (outside tmux)

Command	What it does
tmux new -s NAME	Create a new session called NAME and attach to it
tmux ls	List all running sessions
tmux attach -t NAME	Reattach to session NAME
tmux kill-session -t NAME	Destroy session NAME
tmux kill-server	Destroy every tmux session (use sparingly)

Inside tmux (after pressing Ctrl+a)

Keystroke	What it does
Ctrl+a d	Detach — leave the session running, return to your normal shell
Ctrl+a c	Create a new window
Ctrl+a %	Split current pane vertically (left/right)
Ctrl+a "	Split current pane horizontally (top/bottom)
Ctrl+a then arrow key	Move focus to the pane in that direction

That’s it. Ten commands. The rest of the tutorial layers extras on top, but with these ten you can already work productively.

---

🔍 Am I inside tmux right now?

Two quick checks.

The status bar. When you’re in tmux, there’s a coloured status bar pinned to the bottom of the terminal showing the session name and window list. Something like:

[nafbi]  1:dev*  2:logs  3:claude                    14:32 30-Apr-26

If you see that bar, you’re in tmux. If you don’t, you’re not.

The $TMUX environment variable.

echo $TMUX

• Inside tmux: prints something like /private/tmp/tmux-501/default,12345,0
• Outside tmux: prints a blank line

Why this matters: nesting tmux inside itself is technically possible but rarely what you want. The $TMUX check is how scripts decide whether to skip auto-attach logic.

---

🏋️ The drill — make tmux click

This is the demo that converts skeptics. Run it once, deliberately, and you’ll understand why people who use tmux don’t go back.

Step 1 — Create a session

From your shell:

tmux new -s drill

You’re now inside a tmux session called drill. The status bar appeared at the bottom.

Step 2 — Split the screen

Inside the session, press:

Ctrl+a %

The pane splits vertically. You now have two shells side by side, both inside the same tmux window.

Press Ctrl+a " to add a horizontal split on top of the right pane. Now you have three shells in one screen.

Use the arrow keys to move between them: Ctrl+a →, Ctrl+a ←, Ctrl+a ↑, Ctrl+a ↓.

Step 3 — Run something long-lived in each pane

In the left pane:

htop

In the top-right pane (if you’re on the server):

tail -f /var/log/syslog

In the bottom-right pane:

ping 8.8.8.8

Three live processes, all visible at once.

Step 4 — Detach

Press:

Ctrl+a d

You’re back in your normal shell. The status bar is gone. But the session is still running — those three processes are still going in the background.

Verify:

tmux ls

You’ll see:

drill: 1 windows (created Wed Apr 30 14:32:00 2026)

Step 5 — The magic moment

If you’re connected over SSH to a server, disconnect entirely — close the terminal, kill the SSH connection, do whatever ends the session.

Reconnect. SSH back in.

tmux attach -t drill

Everything is exactly as you left it. htop is still running, the log is still tailing, ping is still pinging. You haven’t lost a single line of output.

That’s the moment tmux clicks.

Step 6 — Clean up

When you’re done, kill the panes one at a time with Ctrl+a x (it’ll ask you to confirm), or just nuke the whole session from outside:

tmux kill-session -t drill

---

🛡️ Common first-time stumbles

• Pressing the prefix wrong. It’s Ctrl+a released, then the next key. Not Ctrl+a+d held together. Take it slow at first.
• Forgetting you’re in tmux. Type tmux ls from inside a session and you’ll see your own session listed. That’s normal — you’re not nested, you’re just attached.
• Trying to scroll with the mouse wheel. By default, the mouse doesn’t work. Stage 2 fixes this. For now, use Ctrl+a [ to enter copy mode, then arrow keys / Page Up / Page Down to scroll. q exits copy mode.
• Running tmux commands at the bash prompt. Things like set -g mouse on are tmux commands, not shell commands. They go in ~/.tmux.conf (covered in Stage 3) or after Ctrl+a : to open the tmux command prompt. The Troubleshooting page has the full breakdown.

---

➡️ Next steps

You’ve got persistence and basic splits. Now learn to live in tmux: multiple windows per session, naming things, copy mode, and the layouts that make tmux feel like an IDE.

Continue to Stage 2 — Daily Driver.

If you specifically want to use tmux for keeping Claude Code alive on the server, the focused Claude Persistent Sessions guide is a quicker path for that single use case.