Introduction to tmux

Introduction to tmux

Before any keybindings, get the mental model right. Once these three ideas land, every tmux command afterwards has a place to live.

---

🎯 What tmux actually is

tmux stands for terminal multiplexer. It sits between you and your shell and gives you three abilities the bare terminal can’t:

1. Persistence. Sessions keep running when you close the terminal, log out, or lose your SSH connection. Reconnect and pick up exactly where you left off.
2. Multiplexing. One terminal window can host many shells simultaneously, in tabs and split panes, without juggling separate terminal windows.
3. Reproducibility. A few lines of script can spin up a complete project workspace — editor, logs, database shell, git status — in one command.

If you’ve ever lost an hour of work to a flaky Wi-Fi disconnect, tmux solves that. If you’ve ever had eight terminal windows scattered across two monitors and no idea which one was running which thing, tmux solves that too.

---

🧠 The three-level mental model

Everything in tmux is one of three things, nested:

Session
└── Window (think: tab)
    └── Pane (think: split inside the tab)

• Session — the top-level container. One per project is a good default. Sessions persist across disconnects. You can have many sessions running at once and switch between them.
• Window — a “tab” inside a session. Each window has its own working directory and shells. Use windows to separate roles within a project: dev, logs, db, git, claude.
• Pane — a split inside a window. Panes share the window’s space — vertical splits, horizontal splits, or grids. Use panes when you want to see two things at once: editor next to logs, server output next to a test runner.

A typical session for a real project looks like this:

Session: nafbi
├── Window 1: dev      ┐
│   ├── Pane 1: editor │  one window, two panes side-by-side
│   └── Pane 2: shell  ┘
├── Window 2: logs     (full window tailing logs)
├── Window 3: db       (full window with a psql shell)
├── Window 4: git      (full window for git operations)
└── Window 5: claude   (full window running claude code)

Five windows, six shells, all inside one tmux session. Detach, walk away, come back tomorrow — every shell is still where you left it.

---

🔑 The prefix key

Every tmux command starts with a prefix key. Throughout this tutorial we use Ctrl+a — that’s the iSu dev server standard, configured in the shipped ~/.tmux.conf. Vanilla tmux out of the box uses Ctrl+b; the iSu config remaps it to Ctrl+a because it sits on the left-hand home row and is much easier on the left pinky.

You press Ctrl+a, release, then press the next key. This is so tmux’s keybindings don’t collide with whatever’s running inside the shells.

Examples:

Keystroke	What it does
Ctrl+a then d	Detach from the current session
Ctrl+a then c	Create a new window
Ctrl+a then %	Split current pane vertically

Throughout this tutorial, that pattern is written as Ctrl+a d, Ctrl+a c, Ctrl+a % — meaning “press Ctrl+a, release, then press the next key.”

On a vanilla tmux setup? Your prefix is Ctrl+b

If you’re following this tutorial outside the iSu environment (for example on a fresh tmux install elsewhere), your prefix is the upstream default Ctrl+b — wherever this page shows Ctrl+a X, substitute Ctrl+b X. The keys after the prefix and the resulting actions are identical.

To check what your prefix is, look in ~/.tmux.conf. If you see lines like these:

unbind C-b
set -g prefix C-a
bind C-a send-prefix

…your prefix is Ctrl+a (matches this tutorial). If those lines aren’t there, you’re on the upstream default Ctrl+b.

Caps Lock as Ctrl on macOS

Pressing the prefix dozens of times an hour is rough on the left pinky. Remap Caps Lock → Control in System Settings → Keyboard → Keyboard Shortcuts → Modifier Keys. Most heavy tmux users do this once and never look back. Stage 3 covers this in more detail.

---

💼 Why tmux pays off

The investment is small — maybe two hours across four stages — and the payoff is permanent. Concrete wins for our team:

• No more lost sessions. SSH drops on flaky networks (especially on the road or on iPad over LTE) used to mean restarting a Claude Code session, re-sourcing env vars, re-tailing logs. With tmux, you just tmux attach and you’re back.
• Project context in one command. A single start-nafbi.sh brings up the editor, the log tail, a git pane, and a Claude window — already in the right directory, already running.
• Pair-friendly. Two engineers can attach to the same session over SSH and see the same screen, useful for incident response or onboarding.
• Long-running tasks. Migrations, backups, training runs, deploys — start them in tmux, detach, come back when they’re done.

---

➡️ Next steps

The mental model is enough background. Move on to Stage 1 — Survival Kit and install tmux, then put the persistence trick into practice. That’s the moment it clicks.