tmux Config Guide for Remote Developers

tmux is the single most important tool for remote developers who work over SSH. When your connection drops, your tmux session keeps running on the server. When you reconnect, you reattach and pick up exactly where you left off — no lost work, no killed processes, no interrupted builds.

This guide covers practical tmux configuration: a solid ~/.tmux.conf, session and window management patterns, plugin setup with tpm, and SSH persistence workflows.

Install tmux

On most Linux servers:

# Debian/Ubuntu
sudo apt-get install tmux

# RHEL/CentOS/Amazon Linux
sudo dnf install tmux

# macOS (local machine)
brew install tmux

# Verify version — 3.3+ recommended
tmux -V

tmux 3.3+ adds popup windows and better mouse handling. If your distro ships an older version, build from source or use a package manager like asdf.

A Practical ~/.tmux.conf

Start with a configuration that makes daily use comfortable. Create or replace ~/.tmux.conf:

# ~/.tmux.conf

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

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

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

# Navigate panes with Vim keys
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Resize panes with Shift+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

# Enable mouse support (scroll, click to select pane/window)
set -g mouse on

# Start windows and panes at index 1 (not 0)
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on

# Increase scrollback buffer
set -g history-limit 50000

# Reduce escape time (important for Neovim/Vim users)
set -sg escape-time 10

# Enable 256 color and true color
set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",xterm-256color:RGB"

# Status bar — minimal and useful
set -g status-interval 5
set -g status-left "#[fg=green][#S] "
set -g status-right "#[fg=cyan]%H:%M #[fg=yellow]%Y-%m-%d"
set -g status-right-length 50
set -g status-bg colour235
set -g status-fg colour255

# Highlight active window in status bar
setw -g window-status-current-style 'fg=colour1 bg=colour19 bold'

# Focus events (required for some editors)
set -g focus-events on

# tmux Plugin Manager bootstrap
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @plugin 'tmux-plugins/tmux-yank'

# tmux-resurrect: restore vim/neovim sessions too
set -g @resurrect-strategy-vim 'session'
set -g @resurrect-strategy-nvim 'session'

# tmux-continuum: auto-save every 15 minutes
set -g @continuum-restore 'on'
set -g @continuum-save-interval '15'

# Initialize TPM (keep at bottom)
run '~/.tmux/plugins/tpm/tpm'

Install tmux Plugin Manager (TPM)

# Clone TPM
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

# Start a new tmux session
tmux new-session -s main

# Inside tmux: install plugins with prefix + I (capital i)
# Ctrl-a + I

# To update plugins later
# Ctrl-a + U

# To remove a plugin
# Ctrl-a + alt-u

Session Management Patterns

For remote development, organize work into named sessions per project:

# Create named sessions
tmux new-session -d -s api        # backend API project
tmux new-session -d -s frontend   # frontend app
tmux new-session -d -s infra      # infrastructure/devops

# List sessions
tmux ls

# Attach to a session
tmux attach-session -t api
tmux attach -t api                 # shorthand

# Switch between sessions from inside tmux
# Ctrl-a + s  (shows session list with tree view)
# Ctrl-a + $  (rename current session)

# Kill a session
tmux kill-session -t infra

# Kill all sessions except current
tmux kill-session -a

Window and Pane Layouts

A typical development layout uses 3 panes: editor, terminal, and logs.

# Inside tmux, create a dev layout script
cat > ~/bin/dev-layout.sh << 'EOF'
#!/bin/bash
# Usage: dev-layout.sh [session-name] [project-path]

SESSION=${1:-dev}
PATH=${2:-$HOME}

tmux new-session -d -s "$SESSION" -c "$PATH"

# Window 1: editor
tmux rename-window -t "$SESSION:1" 'editor'
tmux send-keys -t "$SESSION:editor" 'nvim .' Enter

# Window 2: dev server + logs (vertical split)
tmux new-window -t "$SESSION" -n 'server' -c "$PATH"
tmux split-window -h -t "$SESSION:server"
tmux send-keys -t "$SESSION:server.left" 'npm run dev' Enter
tmux send-keys -t "$SESSION:server.right" 'tail -f logs/app.log' Enter

# Window 3: git + misc terminal
tmux new-window -t "$SESSION" -n 'git' -c "$PATH"

# Attach
tmux attach-session -t "$SESSION"
EOF
chmod +x ~/bin/dev-layout.sh

SSH Persistence with tmux

The core benefit for remote developers: sessions survive disconnects.

# SSH into server and create/attach a named session
ssh user@server.example.com

# On server: attach to existing session or create new one
tmux attach -t work 2>/dev/null || tmux new-session -s work

# From your local machine: one-liner to connect and attach
ssh -t user@server.example.com "tmux attach -t work || tmux new-session -s work"

# Add to ~/.ssh/config for easy access
# Host myserver
#   HostName server.example.com
#   User deploy
#   RemoteCommand tmux attach -t work || tmux new-session -s work
#   RequestTTY force

With tmux-resurrect and tmux-continuum installed, your sessions also survive server reboots — the plugin saves pane contents and running processes, then restores them on tmux attach.

Useful Key Bindings Reference

With the config above (prefix = Ctrl-a):

Action	Keys
Split vertical	`prefix + \|`
Split horizontal	`prefix + -`
Navigate panes	`prefix + h/j/k/l`
List sessions	`prefix + s`
New window	`prefix + c`
Next window	`prefix + n`
Previous window	`prefix + p`
Rename window	`prefix +,`
Detach	`prefix + d`
Enter copy mode	`prefix + [`
Search in buffer	`prefix + [` then `/`
Reload config	`prefix + r`

Copy Mode and Clipboard

For copying text from the terminal buffer with tmux-yank:

# Enter copy mode
# Ctrl-a + [

# Move with vim keys (h/j/k/l, w/b, gg/G, /)
# Select text with v (visual), V (visual line), Ctrl-v (block)
# Copy selection with y (yank — copies to system clipboard with tmux-yank)
# Exit copy mode with q or Escape

# Mouse: with mouse mode on, select text and it copies automatically
# Hold Shift while selecting to bypass tmux and copy from terminal emulator

Performance Tuning for Slow Connections

When working over high-latency SSH connections:

# In ~/.tmux.conf — reduce status bar refresh rate on slow links
set -g status-interval 30     # update every 30s instead of 5s

# Disable window activity monitoring (reduces redraws)
setw -g monitor-activity off

# Use mosh instead of SSH for unreliable connections
# mosh user@server.example.com
# mosh reconnects automatically; combine with tmux for full persistence

# For very slow connections, disable mouse mode
# set -g mouse off
# This reduces the amount of data sent between server and client

Built by theluckystrike — More at zovo.one