tmux Lesson Plan

A progressive curriculum to master tmux through hands-on practice.

Prerequisites

Comfortable with Unix CLI basics — navigating, running commands.

Lesson 1: First Contact

Goal: Understand what tmux does and run your first session.

Concepts

tmux is a terminal multiplexer. It lets you:

• Run multiple terminals in one window
• Detach sessions and reconnect later (survives SSH disconnects)
• Split your screen into panes

Exercises

1. Start and exit tmux

   tmux           # Enter tmux
   exit           # Leave tmux (closes session)

2. Create a named session

   tmux new -s practice

3. Detach and reattach

   # Inside tmux, press: C-b d (Ctrl+b, then d)
   # You're back in your normal shell. The session lives on.
   
   tmux ls                    # See your session
   tmux attach -t practice    # Reconnect

4. Kill the session

   tmux kill-session -t practice

Checkpoint

You understand the session lifecycle: create → detach → attach → kill.

---

Lesson 2: Windows

Goal: Manage multiple terminals within one session.

Concepts

Windows are like browser tabs. Each window has its own shell. You see one window at a time.

Exercises

1. Create a session and add windows

   tmux new -s dev
   # C-b c    Create window
   # C-b c    Create another

2. Navigate windows

   # C-b n    Next window
   # C-b p    Previous window
   # C-b 0    Go to window 0
   # C-b 1    Go to window 1
   # C-b w    Interactive window list

3. Name your windows

   # C-b ,    Rename current window
   # Type: editor

4. Close a window

   # C-b &    Kill window (confirms first)
   # Or just type: exit

Checkpoint

Create 3 windows named “editor”, “server”, “logs”. Jump between them by number.

---

Lesson 3: Panes

Goal: Split windows into multiple views.

Concepts

Panes divide a window into sections. All panes in a window display simultaneously.

• C-b % splits left/right (think: % has two circles side by side)
• C-b " splits top/bottom (think: ” has two dots stacked)

Exercises

1. Split and navigate

   # Start fresh
   tmux new -s panes
   
   # C-b %      Split vertically (left/right)
   # C-b "      Split horizontally (top/bottom)
   # C-b ←↑↓→   Move between panes

2. Zoom a pane

   # C-b z     Toggle fullscreen on current pane
   # C-b z     Toggle back

3. Close panes

   # C-b x     Kill pane (with confirmation)
   # Or: exit

4. Resize panes

   # C-b C-←↑↓→    Resize (small steps)
   # C-b M-←↑↓→    Resize (big steps)

Checkpoint

Create this layout:

+--------+--------+
|        |   B    |
|   A    +--------+
|        |   C    |
+--------+--------+

Start in window → split right → go to right pane → split down.

---

Lesson 4: Copy Mode

Goal: Scroll history and copy text.

Concepts

Terminals lose scrollback when they fill. Copy mode lets you scroll, search, and yank text.

Exercises

1. Generate scrollback

   tmux new -s copy
   seq 1 500          # Print 500 lines

2. Enter copy mode and scroll

   # C-b [         Enter copy mode
   # ↑ ↓           Scroll line by line
   # C-u C-d       Scroll half pages
   # g             Go to top
   # G             Go to bottom
   # q             Exit copy mode

3. Search

   # C-b [         Enter copy mode
   # /250          Search forward for "250"
   # n             Next match
   # N             Previous match

4. Copy and paste

   # C-b [         Enter copy mode
   # Space         Start selection
   # (move cursor)
   # Enter         Copy and exit
   # C-b ]         Paste

Checkpoint

Copy lines 100-110 from your scrollback and paste them.

---

Lesson 5: Configuration

Goal: Customize tmux to your preferences.

Exercises

1. Create a config file

   touch ~/.tmux.conf

2. Add basic improvements

   ~/.tmux.conf

   # Start numbering at 1 (easier to reach)
   set -g base-index 1
   setw -g pane-base-index 1
   
   # Enable mouse
   set -g mouse on
   
   # Vi mode in copy mode
   setw -g mode-keys vi
   
   # Increase history
   set -g history-limit 50000

3. Reload config

   # Inside tmux:
   # C-b :
   # source-file ~/.tmux.conf

4. Add intuitive splits

   # ~/.tmux.conf (append)
   
   # Split with | and -
   bind | split-window -h -c "#{pane_current_path}"
   bind - split-window -v -c "#{pane_current_path}"

Checkpoint

Your config loads. C-b | splits horizontally. Mouse scrolling works.

---

Lesson 6: Session Workflow

Goal: Use sessions for project organization.

Concepts

One session per project keeps contexts separate. Detach from one, attach to another.

Exercises

1. Create project sessions

   tmux new -s project-a -d    # -d = detached
   tmux new -s project-b -d
   tmux ls                     # See both

2. Switch sessions

   tmux attach -t project-a
   # C-b s         List sessions (interactive)
   # C-b )         Next session
   # C-b (         Previous session

3. Session within session (avoid this)

   # If you see "sessions should be nested..." you're in tmux already.
   # Use C-b s to switch, don't nest.

Checkpoint

Maintain 2 project sessions. Switch between them without detaching.

---

Lesson 7: Scripting

Goal: Automate your development environment.

Exercises

1. Create a dev script

   ~/bin/dev-session.sh

   #!/bin/bash
   SESSION="dev"
   
   # Exit if session exists
   tmux has-session -t $SESSION 2>/dev/null && {
       tmux attach -t $SESSION
       exit 0
   }
   
   # Create session with editor window
   tmux new-session -d -s $SESSION -n "editor"
   tmux send-keys -t $SESSION:editor "nvim ." C-m
   
   # Create server window
   tmux new-window -t $SESSION -n "server"
   tmux send-keys -t $SESSION:server "npm run dev" C-m
   
   # Create split window for git and tests
   tmux new-window -t $SESSION -n "tools"
   tmux split-window -h -t $SESSION:tools
   tmux send-keys -t $SESSION:tools.0 "git status" C-m
   
   # Go back to editor
   tmux select-window -t $SESSION:editor
   
   # Attach
   tmux attach -t $SESSION

2. Make it executable

   chmod +x ~/bin/dev-session.sh

3. Use target syntax

   # session:window.pane
   tmux send-keys -t dev:editor.0 "echo hello" C-m
   tmux select-pane -t dev:tools.1

Checkpoint

Run your script. It creates your ideal workspace in one command.

---

Lesson 8: Advanced Tricks and Integration

Goal: Power user techniques and terminal emulator integration.

Exercises

1. Synchronize panes (run command on all panes)

   # Create 3 panes
   # C-b :
   # setw synchronize-panes on
   # Type a command - it appears in all panes
   # setw synchronize-panes off

2. Capture pane to file

   # C-b :
   # capture-pane -S -3000
   # save-buffer ~/debug.log

3. Break pane to window

   # C-b !    Move current pane to its own window

4. Join windows

   # C-b :
   # join-pane -s 2 -t 1    # Move window 2 into window 1 as pane

5. Pipe pane output

   # C-b :
   # pipe-pane -o 'cat >> ~/output.log'
   # (all output goes to file until you run pipe-pane again)

Checkpoint

Sync 3 panes. Run uptime in all of them simultaneously.

Terminal Emulator Integration

iTerm2’s Control mode (-CC) makes tmux feel native: tmux windows become iTerm tabs, tmux panes become iTerm splits, and you get native scrollback, copy/paste, and search. The session persists when you close iTerm. See Terminal Emulators for a full comparison of -CC mode vs standard tmux and guidance on when each approach fits.

1. Start an integrated session

   tmux -CC new -s integrated

   iTerm takes over the UI. The window looks like a normal iTerm window.

2. Use native shortcuts

   # Instead of C-b c:
   Cmd+T              # New tab (tmux window)
   
   # Instead of C-b % and C-b ":
   Cmd+D              # Split right
   Cmd+Shift+D        # Split down
   
   # Instead of C-b ←↑↓→:
   Cmd+Option+Arrow   # Navigate panes
   
   # Instead of C-b x:
   Cmd+W              # Close pane

3. Scroll and search natively

   seq 1 500          # Generate output
   # Scroll with trackpad or mouse wheel
   Cmd+F              # Search (iTerm's search, not tmux copy mode)

4. Detach and reattach through -CC

   # Option 1: Close iTerm entirely (Cmd+Q)
   # Option 2: tmux detach (or C-b d still works)
   
   # Later:
   tmux -CC attach -t integrated

5. Configure iTerm for tmux

   Open iTerm Preferences (Cmd+,) then General then tmux:

   • “Open tmux windows as”: Tabs in a new window
   • Check “Automatically hide the tmux client session”
   • Check “When attaching, restore windows as tabs”

6. Mix integration with regular tmux

   # In iTerm with -CC:
   tmux -CC new -s work
   
   # From another terminal (SSH, different machine):
   tmux attach -t work    # Regular attach works alongside

7. Escape hatch

   # If you need to exit integration mode without detaching:
   Cmd+Shift+I        # Detach from integration, return to normal iTerm

Final Checkpoint

Start tmux -CC new -s test. Create 3 tabs and split one into panes using only Cmd shortcuts. Close iTerm entirely. Reopen and run tmux -CC attach -t test. Everything should restore.

---

Practice Projects

Project 1: Monitoring Dashboard

Create a session with:

• Window 1: htop
• Window 2: Split into 4 panes showing different log files

Project 2: Dev Environment

Script that creates:

• Window “code”: editor
• Window “run”: split with server and file watcher
• Window “test”: test runner
• Window “git”: git status and lazygit

Project 3: SSH Resilience

SSH to a server, start tmux, run a long job, disconnect intentionally, reconnect, verify job continued.

---

Key Bindings Summary

Stage	Must Know
Beginner	C-b d C-b c C-b n C-b % C-b " C-b ←↑↓→
Daily	C-b z C-b [ C-b s C-b w C-b , C-b x
Power	C-b : C-b ! C-b & sync-panes, scripting
iTerm	Cmd+T Cmd+D Cmd+Shift+D Cmd+Option+Arrow

See Also

• tmux — Quick reference: key bindings, config, scripting
• Terminal Emulators — iTerm2 vs Ghostty, tmux -CC integration
• Ghostty Lesson Plan — 8 lessons for the terminal emulator alongside tmux
• Operating Systems Lesson Plan — Processes, signals, and the environment tmux manages