tmux Setup

Published: March 8, 2026 · Last edited: March 8, 2026

A tmux configuration that keeps your terminal organised, survives disconnects, and stays out of your way.

Reference: This guide follows the official tmux Getting Started documentation.

Core Philosophy

• Sessions over tabs — a session per project, not a tab per task
• Persistent work — detach and reattach; your layout survives SSH drops
• Sensible prefix — Ctrl+a beats Ctrl+b for reachability
• Vim-style navigation — consistent muscle memory across tools
• Minimal visual noise — a clean status bar that shows what matters

1. Installation

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# Check version (tmux 3.0+ recommended)
tmux -V

2. Core ~/.tmux.conf

Create ~/.tmux.conf:

# ============================================================
# PREFIX
# ============================================================

# Change prefix from Ctrl+b to Ctrl+a (easier to reach)
unbind C-b
set -g prefix C-a
bind C-a send-prefix


# ============================================================
# GENERAL
# ============================================================

set -s default-terminal "tmux-256color"     # 256-colour support (server option)
set -g history-limit 50000                  # Longer scrollback
set -s escape-time 0                        # No delay for Escape key (server option)
set -g focus-events on                      # Pass focus events to apps
setw -g aggressive-resize on               # Resize to smallest active client


# ============================================================
# INDEXING
# ============================================================

set -g base-index 1          # Windows start at 1, not 0
setw -g pane-base-index 1    # Panes start at 1, not 0
set -g renumber-windows on   # Renumber windows when one is closed


# ============================================================
# MOUSE
# ============================================================

set -g mouse on   # Click to select panes/windows, scroll to scroll


# ============================================================
# VISUAL FEEDBACK
# ============================================================

set -g visual-activity off   # No bell on window activity
setw -g monitor-activity on  # Highlight windows with activity


# ============================================================
# STATUS BAR
# ============================================================

set -g status-interval 5          # Refresh every 5 seconds
set -g status-position bottom

# Left: session name
set -g status-left " #S "
set -g status-left-length 20

# Right: host and time
set -g status-right " #H  %H:%M "
set -g status-right-length 40

# Window list: highlight active window
setw -g window-status-current-format " #I:#W "
setw -g window-status-format " #I:#W "


# ============================================================
# PANE SPLITTING
# ============================================================

# Split with | and - (intuitive direction)
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
unbind '"'
unbind %

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


# ============================================================
# NAVIGATION
# ============================================================

# 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 resizing (hold prefix, tap arrow)
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

# Fast window switching with Prefix + number (already default, just a reminder)
# Prefix+1 ... Prefix+9


# ============================================================
# COPY MODE
# ============================================================

setw -g mode-keys vi          # Vi keys in copy mode

bind Enter copy-mode          # Also enter copy mode with Prefix+Enter (default is Prefix+[)
bind -T copy-mode-vi v send -X begin-selection
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"   # macOS
bind -T copy-mode-vi Escape send -X cancel


# ============================================================
# RELOAD
# ============================================================

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

3. Session Management

Sessions are the top-level unit in tmux — one per project.

# Start a new named session
tmux new -s myproject

# List all sessions
tmux ls

# Attach to a session
tmux attach -t myproject

# Detach from the current session (keep it running)
# Prefix + d

# Kill a session
tmux kill-session -t myproject

Detaching is not quitting. Your processes keep running and you can reattach from anywhere.

4. Window and Pane Basics

Action	Key
New window	Prefix + c
Next window	Prefix + n
Previous window	Prefix + p
Switch to window N	Prefix + N
Rename window	Prefix + ,
Close window	Prefix + &
Split vertically	Prefix + |
Split horizontally	Prefix + -
Navigate panes	Prefix + h/j/k/l
Close pane	Prefix + x
Zoom pane (toggle fullscreen)	Prefix + z

5. Copy Mode

Copy mode lets you scroll and select text without a mouse.

Action	Key
Enter copy mode	Prefix + [ (default) or Prefix + Enter (custom)
Start selection	v (custom) or Space (default vi)
Copy selection	y (copies to system clipboard)
Cancel	q or Escape (custom)
Search backward	?
Search forward	/
Page up/down	Ctrl+u / Ctrl+d

6. Daily Workflow

1. Start your day: tmux new -s work — one session for your main project
2. Organise by task: open a window per context (e.g. editor, server, logs)
3. Side work: Prefix + $ to rename the session, Prefix + ( / ) to switch between sessions
4. SSH safely: SSH into a remote machine, run tmux new -s remote — if you drop, reattach with tmux attach
5. Zoom in: Prefix + z to focus a single pane, same key to restore the layout
6. Reload config: Prefix + r after editing ~/.tmux.conf

7. Shell Timeout & Security

The CLI Setup guide sets TMOUT=1800, which auto-logs out idle shells after 30 minutes. Inside tmux this kills any running processes in idle panes — directly at odds with persistent sessions. You have two options:

Option A — Keep TMOUT, accept the behaviour

Idle shells in tmux panes log out after 30 minutes of inactivity, terminating any running processes in them. The tmux session itself stays alive but panes will show a logged-out shell.

Choose this if security is the priority and you don't rely on long-running processes in panes.

No changes needed — this is the default behaviour when both guides are followed together.

Option B — Replace TMOUT with tmux's native lock (recommended)

Unset TMOUT inside tmux and use tmux's lock-after-time instead. The tmux client locks after inactivity — the screen is protected but processes keep running.

Step 1 — Add to ~/.zshrc:

# Disable shell auto-logout inside tmux; tmux handles locking instead
[[ -n "$TMUX" ]] && unset TMOUT

Step 2 — Add to ~/.tmux.conf:

# Lock the tmux client after 30 minutes of inactivity (processes keep running)
set -g lock-after-time 1800

To unlock, press any key and enter your system password.

Choose this if you rely on persistent processes (servers, watchers, builds) and want the session protected without destroying it.

8. Customization

• Prefix key: Ctrl+a matches GNU Screen muscle memory; change back to Ctrl+b if you prefer the default
• Clipboard on Linux: replace pbcopy with xclip -in -selection clipboard or wl-copy for Wayland
• Theme: install tpm and add dracula/tmux or catppuccin/tmux for a styled status bar
• Sessionizer: pair with a shell script and fzf to fuzzy-find and jump to any project session in one keystroke

Remember: configure only what creates friction, not what looks impressive.