Stage 3 — Customisation

Stage 3 — Customisation

Default tmux is functional but rough. This stage turns it into a comfortable, ergonomic environment — the config additions worth memorising, the Mac terminal setup that pays off daily, and the multi-session moves you’ll use once you have more than one project running.

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. The config additions below work the same regardless of which prefix you use. See the Introduction for how to check.

---

🎯 Goal

After this stage you will be able to:

• Read and edit ~/.tmux.conf without breaking anything.
• Apply a config you’ll actually want to keep, with intuitive splits, vim-style navigation, mouse support, and clipboard sync.
• Reload config changes without restarting tmux.
• Work across multiple sessions fluidly.
• Pick the right Mac terminal app and ergonomic settings for tmux-heavy workflows.

---

📋 Prerequisites

• Stages 1 and 2 complete.
• A text editor you’re comfortable with (nano, vim, nvim, or VS Code via code ~/.tmux.conf).

---

📂 Where the config lives

tmux reads ~/.tmux.conf on startup. One file, plain text, lives in your home directory both on macOS and on the server.

If you don’t have one yet, create it:

touch ~/.tmux.conf

The config syntax is tmux’s own command language — not bash, not YAML. A line like set -g mouse on is a tmux command. Don’t paste these lines into a bash prompt — they’ll error. The Troubleshooting page goes deeper on this distinction; it’s the most common new-user mistake.

---

✅ The starting baseline

A reasonable starting ~/.tmux.conf already covers most quality-of-life essentials:

# Mouse support: drag pane borders, click panes, scroll wheel
set -g mouse on

# Keep more scrollback (default 2000 is too small)
set -g history-limit 50000

# Number windows from 1 instead of 0 (so 0..9 keys feel right)
set -g base-index 1
setw -g pane-base-index 1

# Renumber remaining windows when one is closed
set -g renumber-windows on

# Don't rename windows automatically once you've named them
setw -g automatic-rename off

# Remove the small delay before tmux acknowledges Esc
set -sg escape-time 0

# Use vi-style keys in copy mode
setw -g mode-keys vi

# Don't kill the session when the last client detaches
set -g destroy-unattached off

If your ~/.tmux.conf already has these (the shipped iSu config does), you’re good. Otherwise, drop them in.

---

🚀 The recommended additions

Below are the additions that turn tmux from “works fine” into “I never want to leave this.” Add them to ~/.tmux.conf.

Clipboard sync to macOS

# Send selections to the system clipboard (works with iTerm2, Ghostty,
# modern Terminal.app, and Termius with OSC 52 enabled)
set -g set-clipboard on

After this, y in copy mode copies to the macOS clipboard. Cmd+V in any other app pastes it. Same for iPad over Termius if OSC 52 is enabled in Termius settings.

Reload config without restarting

# Reload ~/.tmux.conf with Prefix + r
bind r source-file ~/.tmux.conf \; display-message "Config reloaded"

After this, edit ~/.tmux.conf, then press Ctrl+a r to apply changes immediately. No more “kill all sessions to reload config.”

Memorable splits in current path

# Use | for vertical split, - for horizontal split
# New panes inherit the working directory of the current pane
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

Why this matters: the default keys (% and ") are unmemorable. | looks like a vertical split, - looks like a horizontal split. And the -c "#{pane_current_path}" part means new panes start in the same directory you were in — not your home directory.

The original Ctrl+a % and Ctrl+a " still work too; you’re adding bindings, not removing them.

Vim-style pane navigation

# Move between panes with hjkl (vim-style)
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

After this, Ctrl+a h/j/k/l moves between panes. Faster than reaching for arrow keys, especially if you’re already in vim-mode brain.

Vim-style pane resizing

# Resize panes with HJKL (capitals), repeatable
bind -r H resize-pane -L 5
bind -r J resize-pane -D 5
bind -r K resize-pane -U 5
bind -r L resize-pane -R 5

The -r flag means repeatable: press Ctrl+a H, then H H H without re-pressing Ctrl+a. Holds the prefix open for ~500ms after each press.

New windows in the current path

# Ctrl+a c creates a new window in the current pane's directory
bind c new-window -c "#{pane_current_path}"

By default Ctrl+a c opens a new window in your home directory. With this, the new window starts wherever you were.

Editor-friendly events

# Tell editors (vim, nvim) when they regain focus, so autoread works
set -g focus-events on

If you use vim or nvim and have :set autoread enabled, this lets the editor reload files that changed on disk when you switch back to its pane.

Copy-mode: vim-style selection

# In copy mode, v starts selection, y copies and exits
bind -T copy-mode-vi v send-keys -X begin-selection
bind -T copy-mode-vi y send-keys -X copy-selection-and-cancel

Ctrl+a [ to enter copy mode, v to start selecting, move with hjkl, y to copy and exit.

---

🔄 Applying config changes

Three ways to apply edits to ~/.tmux.conf:

1. Edit + reload binding (after the recommended addition above): edit the file, then Ctrl+a r from any session. Fastest.
2. Edit + restart tmux: edit the file, kill all sessions (tmux kill-server), reopen. Heavy-handed but guaranteed clean.
3. Run a single command interactively: press Ctrl+a : to open tmux’s command prompt, then type the command (without set -g, just mouse on, etc.) and press Enter. Useful for testing one change before committing it to the file.

The single most common new-user error is pasting ~/.tmux.conf lines into a bash shell and getting -bash: set: -g: invalid option. Those lines are tmux commands, not bash. See the Troubleshooting page for the full breakdown of contexts.

---

🔧 Bash aliases for daily use

Pair the tmux config with shell aliases. Add to ~/.bashrc (or ~/.zshrc if you use zsh):

# tmux quality-of-life aliases
alias tls='tmux ls'                        # list sessions
alias ta='tmux attach -t'                  # attach: ta nafbi
alias tn='tmux new -s'                     # new: tn nafbi
alias tk='tmux kill-session -t'            # kill: tk nafbi

# Project-specific quick attach
alias tclaude='tmux attach -t claude || tmux new -s claude'

# Open a fresh work session that bypasses any auto-attach logic
alias twork='NO_AUTO_TMUX=1 tmux new -s work-$(date +%H%M)'

After editing ~/.bashrc:

source ~/.bashrc

Then tls, ta nafbi, tn newproject, tk drill all just work.

---

🔀 Multi-session workflow

Once you have more than one project, learn these keystrokes:

Keystroke	Action
Ctrl+a s	Interactive session picker (tree of sessions and windows)
Ctrl+a w	Interactive window picker across all sessions
Ctrl+a L	Toggle to last session (the Alt+Tab equivalent)
Ctrl+a (	Switch to previous session (alphabetic)
Ctrl+a )	Switch to next session (alphabetic)
Ctrl+a $	Rename current session
Ctrl+a d	Detach

The two that matter most are Ctrl+a s (open the session picker — it’s interactive and shows the full tree) and Ctrl+a L (rapid toggle between two sessions you’re juggling).

Detaching from one session and attaching to another from the shell:

# Detach from current session: Ctrl+a d
tmux attach -t thrivesend

Or skip the trip back through the shell — switch directly inside tmux with Ctrl+a s.

---

🍎 Mac terminal setup

The terminal app you choose matters more than tmux config — a sluggish or buggy terminal makes everything feel sluggish or buggy. Recommendations, in order:

1. iTerm2 (recommended)

iTerm2 is the most polished tmux experience on Mac. Two killer features:

• Native scroll works inside tmux out of the box (with mouse on).
• Control mode (tmux -CC) makes iTerm2 render tmux windows as native iTerm2 tabs and panes. Cmd+T creates a tmux window, Cmd+D splits a tmux pane. It’s tmux underneath, but it feels like the terminal natively understood it.

To use control mode:

# Start a new session in control mode
tmux -CC new -s nafbi

# Or attach to an existing session in control mode
tmux -CC attach -t nafbi

2. Ghostty

Ghostty is fast, GPU-accelerated, and has excellent OSC 52 clipboard support. Doesn’t have iTerm2’s tmux integration, but if you don’t need that, Ghostty’s rendering is silky.

3. Warp

Warp is fine, but its block-based UI fights with tmux’s whole-screen ownership. Workable but not ideal.

4. Terminal.app (default)

Ships with macOS. Modern versions (Sonoma+) have OSC 52 support and clipboard sync. Limited customisation but zero install. Fine as a fallback.

Caps Lock → Ctrl

The single biggest ergonomic win for tmux users:

1. System Settings → Keyboard → Keyboard Shortcuts → Modifier Keys
2. Pick your keyboard
3. Set Caps Lock to Control
4. Click OK

Now your left pinky reaches Ctrl without leaving the home row. After a week you’ll wonder how you lived without it.

Homebrew install

Already covered in Stage 1, but the one-liner:

brew install tmux

To upgrade later:

brew upgrade tmux

---

📱 Working from iPad

iPad with Termius is a workable secondary environment for tmux-heavy SSH work, but a few settings make it much better.

Termius settings to enable

1. OSC 52 clipboard — Termius → Settings → Terminal → Sequences → enable OSC 52. Without this, y in copy mode doesn’t reach the iPad clipboard.
2. Snippets for one-tap attach — Save tmux attach -t nafbi as a Termius snippet. One tap on a saved server profile gets you back into the project.
3. Bluetooth keyboard recommended — soft keyboard works but is slow for tmux’s keystroke-heavy nature. A Magic Keyboard or any Bluetooth keyboard with a real Ctrl key turns iPad into a respectable second-screen workstation.

Caveats:

• Some keyboards lack a Ctrl key on the home row. Apple Magic Keyboard for iPad has Ctrl in the bottom-left corner. The Caps Lock → Ctrl trick can be done in iPadOS too (Settings → General → Keyboard → Hardware Keyboard → Modifier Keys).
• Mouse-mode pane drag works in Termius. Pinch-to-zoom does not interact with tmux zoom (Ctrl+a z).

---

🎯 A complete recommended ~/.tmux.conf

Putting it all together — the config you can copy in and start with:

# ── Sensible defaults ────────────────────────────────────
set -g mouse on
set -g history-limit 50000
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on
setw -g automatic-rename off
set -sg escape-time 0
setw -g mode-keys vi
set -g destroy-unattached off
set -g focus-events on

# ── Clipboard sync ───────────────────────────────────────
set -g set-clipboard on

# ── Reload config ────────────────────────────────────────
bind r source-file ~/.tmux.conf \; display-message "Config reloaded"

# ── Memorable splits in current path ─────────────────────
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

# ── Vim-style pane navigation ────────────────────────────
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# ── Vim-style pane resize (repeatable) ───────────────────
bind -r H resize-pane -L 5
bind -r J resize-pane -D 5
bind -r K resize-pane -U 5
bind -r L resize-pane -R 5

# ── New windows in current path ──────────────────────────
bind c new-window -c "#{pane_current_path}"

# ── Copy-mode: vim-style selection ───────────────────────
bind -T copy-mode-vi v send-keys -X begin-selection
bind -T copy-mode-vi y send-keys -X copy-selection-and-cancel

Save this to ~/.tmux.conf, reload (Ctrl+a r if you already added the binding, or restart tmux otherwise), and you’re set.

---

➡️ Next steps

Config done, ergonomics dialled in, multi-session workflow understood. Now learn to skip the setup entirely with project startup scripts — one command brings up your whole workspace.

Continue to Stage 4 — Automation.