Terminal multiplexing: beyond the basics

I was forty minutes into a database migration on a production server—the kind that takes an hour and absolutely cannot be interrupted—when the network dropped. Three seconds of silence. Then the terminal declared "Connection to server closed." The migration script was running. Somewhere on that server, database tables were being restructured, constraints were being added, indexes were being rebuilt. I had no idea what state it was in. Whether it had crashed. Whether I needed to roll back. Whether rerunning it would corrupt data or safely resume where it left off.

I reconnected, held my breath, and ran tmux ls. The session was still there. tmux attach and everything reappeared exactly as I'd left it—the migration script still running, progress output continuing to scroll, current operation visible. The migration completed successfully ten minutes later. My SSH connection had dropped. The migration never noticed.

This is what terminal multiplexers do: they decouple your terminal interface from the processes running within it. The terminal you type into becomes a window onto a persistent session that continues running independently. Network drops, closed terminal windows, even rebooting your local machine—none of these affect processes running in a multiplexer session. For local work, this means your development environment persists across terminal crashes and desktop restarts. For remote work, this means SSH disconnections become irrelevant interruptions rather than catastrophic failures.

tmux—the terminal multiplexer that's become ubiquitous on servers—does more than just preserve sessions. It provides organised workspace management, allowing you to split a single terminal into multiple panes, create multiple windows within a session, and run multiple sessions simultaneously. You can attach to sessions from multiple machines, enabling collaboration where two people work in the same terminal environment. You can synchronise input across panes, sending identical commands to multiple servers simultaneously. The feature set extends far beyond session persistence, but session persistence is why most people start using tmux and why it remains essential infrastructure.

The architecture is straightforward. tmux runs as a server process on the machine where you start it. This server manages sessions, windows, and panes. When you interact with tmux—typing commands, creating windows, splitting panes—you're connecting as a client to this server. The client/server split is what enables persistence. Your terminal is just a client displaying what the server maintains. Close the client, the server continues running. Reconnect, and you're viewing the same session state the server maintained whilst you were disconnected.

The difference becomes obvious when you see it side by side. Without tmux, a database upgrade runs directly under your SSH session:

# Traditional SSH - if connection drops, this process dies
ssh user@server
sudo upgrade-database

If that SSH connection drops, the process terminates. With tmux, the process runs under the tmux server:

# With tmux - process continues even if connection drops
ssh user@server
tmux new -s database-work           # Create new persistent session
sudo upgrade-database               # This keeps running even if SSH dies

The connection can drop, your terminal can crash, your laptop can run out of battery. The tmux server keeps running on the remote machine, and everything you started within that session continues uninterrupted. When you reconnect:

# Connection dropped? No worries
ssh user@server
tmux attach -t database-work        # Everything's still there

The session reappears exactly as you left it. Output you missed whilst disconnected is preserved in the scrollback buffer. The database upgrade that was running is still running. From the process's perspective, nothing happened.

Local versus remote tmux

tmux runs either on your local machine or on remote servers, and understanding the distinction matters for structuring your workflow effectively. When tmux runs locally, the server process exists on your computer, managing sessions that persist as long as your machine stays running. Close your terminal emulator, the local tmux server continues. Reopen your terminal, attach to the session, and everything's there. Local tmux provides workspace organisation—instead of juggling multiple terminal windows across your desktop, you maintain a single organised tmux session with multiple windows and panes.

Local tmux excels at organising multiple aspects of a single project. You might run your development server in one pane whilst watching test results in another, keeping git commands in a third pane and logs in a fourth. The advantage isn't just organisation—it's persistence. Your terminal emulator crashes occasionally. Your desktop environment restarts after updates. The tmux server survives these disruptions, preserving your workspace exactly as you left it. You lose seconds reattaching to your session rather than minutes reconstructing your environment.

Remote tmux provides the same benefits but with network resilience added. The tmux server runs on the remote machine, keeping sessions alive regardless of your connection status. SSH into a server, start a tmux session, launch your processes. Your connection can drop an hour later and everything continues running. You can reconnect from a different computer—from your laptop instead of your desktop, from your phone in an emergency, from a colleague's machine—and attach to the same session. The workspace exists on the server, accessible from anywhere you can SSH from.

The practical difference emerges in scope and accessibility. Local tmux sessions persist until your machine reboots. Remote tmux sessions persist until the server reboots, which might be months for stable servers. Local tmux is accessible only from your machine. Remote tmux is accessible from anywhere. Local tmux organises your personal development environment. Remote tmux enables server management, remote development, and team collaboration where multiple people attach to shared sessions.

Most developers use both simultaneously. A local tmux session organises your development environment—code editor, local servers, test watchers, git operations. A remote tmux session manages your production or staging infrastructure—application logs, system monitoring, maintenance commands, database queries. When your network drops, your local environment stays organised and your remote processes keep running. When you switch machines, you reconnect to the remote session and pick up exactly where you left off. The combination provides both local organisation and remote resilience.

Configuration essentials

tmux's default configuration is functional but not optimal. Mouse support disabled, window numbering starting at zero, minimal scrollback buffer, sluggish escape key handling—these defaults reflect tmux's origins when different assumptions about terminal usage prevailed. A proper configuration removes friction and makes tmux feel natural:

# Enable mouse support for switching panes/windows
set -g mouse on

# Start window numbering at 1
set -g base-index 1
setw -g pane-base-index 1

# Increase scrollback buffer size
set-option -g history-limit 50000

# Improve color handling
set-option -g default-terminal "screen-256color"

# Reduce escape-time (improves vim responsiveness)
set-option -g escape-time 10

# Custom key bindings for splitting windows
bind-key | split-window -h -c "#{pane_current_path}"
bind-key - split-window -v -c "#{pane_current_path}"

# Easy config reload
bind-key r source-file ~/.tmux.conf \; display-message "tmux.conf reloaded."

Mouse support lets you click between panes and scroll through output naturally. Starting window and pane numbering at 1 instead of 0 matches keyboard layout—the 1 key is leftmost on your number row, so window 1 should be leftmost in tmux. The expanded scrollback buffer (50,000 lines instead of the default 2,000) means you can scroll back through hours of output without losing history. Reducing escape-time from the default 500ms to 10ms eliminates the noticeable delay when pressing Escape in vi or vim. Custom split bindings using | for horizontal and - for vertical feel more intuitive than the defaults. The reload binding lets you test configuration changes without restarting tmux.

Remote development workspace

Remote development with tmux transforms a basic SSH connection into a persistent, organised development environment. Instead of running commands directly under SSH where any disconnection terminates your work, you create a structured workspace that survives network issues, organises different aspects of development into logical spaces, and persists between connections regardless of which machine you're connecting from.

#!/bin/bash

ssh user@remote-server bash -c '
    # Create new tmux session named "dev" if it doesn't exist -d flag starts it in detached mode, so it won't attach immediately
    tmux new-session -d -s dev

    # Window 1: Code Editor and Development Server
    # ---------------------------------
    # This is your main development window
    tmux send-keys -t dev "cd /path/to/project" C-m
    tmux send-keys -t dev "nano ." C-m  # Or your preferred editor

    # Split the window horizontally for running your development server
    tmux split-window -h -t dev
    tmux send-keys -t dev:1.2 "npm run dev" C-m

    # Resize the split to give editor more space
    tmux resize-pane -t dev:1.1 -R 20

    # Window 2: Git and System Monitoring
    # ---------------------------------
    # Create a new window for version control and system stats
    tmux new-window -t dev
    tmux send-keys -t dev:2 "git status" C-m

    # Split window for system monitoring
    tmux split-window -v -t dev
    tmux send-keys -t dev:2.2 "htop" C-m

    # Window 3: Log Monitoring
    # ---------------------------------
    # Dedicated window for watching application logs
    tmux new-window -t dev
    tmux send-keys -t dev:3 "tail -f /var/log/nginx/error.log" C-m

    # Select first window and its main pane
    tmux select-window -t dev:1
    tmux select-pane -t dev:1.1
'

# Connect to the session
ssh -t user@remote-server "tmux attach -t dev"

This creates three specialised windows, each serving a distinct purpose. The first window splits between your code editor and the development server, letting you see compilation errors and runtime output immediately without context switching. The second window combines version control operations with system resource monitoring—you can track git status whilst watching CPU and memory usage. The third window dedicates full focus to application logs, isolated from other distractions so you can quickly review output when issues arise.

The pattern extends beyond this specific configuration. API development benefits from panes monitoring requests, error logs, and test results simultaneously. Database work needs query editors alongside log monitors and performance metrics. DevOps tasks require watching multiple log streams whilst keeping command history and system metrics visible. Team collaboration becomes straightforward when multiple people attach to shared sessions, maintaining consistent environments and enabling immediate handoffs without explaining terminal state.

Synchronized panes for multi-server management

Managing multiple servers simultaneously becomes practical with tmux's pane synchronization. SSL certificate updates across production servers, security patches deployed fleet-wide, resource monitoring during high-traffic events—these tasks benefit from executing identical commands across multiple machines simultaneously. Without synchronization, you connect to each server individually, type the same commands repeatedly, and risk missing servers or making typos. With synchronized panes, what you type in one pane executes across all of them:

#!/bin/bash

# Create new session
tmux new-session -d -s servers

# Split window for multiple servers
tmux split-window -h
tmux split-window -v
tmux select-layout tiled

# Connect to different servers in each pane
tmux send-keys -t servers.0 'ssh prod-1' C-m
tmux send-keys -t servers.1 'ssh prod-2' C-m
tmux send-keys -t servers.2 'ssh prod-3' C-m

# Enable synchronization
tmux set-window-option synchronize-panes on

# Attach to session
tmux attach -t servers

Nested tmux sessions

Running tmux locally whilst also running tmux on remote servers creates nested sessions—tmux within tmux. The problem is distinguishing which level receives your commands. By default, all tmux sessions use Ctrl-b as the command prefix. Press Ctrl-b in a nested setup and the outer tmux session captures it. The inner session never sees the command.

The solution is configuring different prefix keys for local and remote sessions:

# In your local ~/.tmux.conf change the prefix for local sessions
set-option -g prefix C-a
unbind-key C-b
bind-key C-a send-prefix

# In your remote ~/.tmux.conf keep the default prefix for remote sessions
set-option -g prefix C-b

Now Ctrl-a controls your local tmux session, Ctrl-b controls remote sessions. The mental model becomes clear: Ctrl-a for local operations, Ctrl-b for remote operations. When SSH'd into a server running tmux, Ctrl-b commands that server's tmux. When working locally, Ctrl-a commands your local tmux. The ambiguity disappears.

Combined local and remote workflows

Real development often requires both local and remote tmux simultaneously. Frontend development happens locally—running build tools, executing tests, monitoring compilation. Backend development happens remotely—managing API servers, watching logs, monitoring resources. These environments need to coexist without interference:

#!/bin/bash

# Local development session
tmux new-session -d -s frontend
tmux send-keys -t frontend 'npm run dev' C-m
tmux split-window -v
tmux send-keys -t frontend 'npm run test:watch' C-m

# Remote API development session
ssh -t api-server "tmux new-session -d -s backend
tmux send-keys 'cd /path/to/api' C-m
tmux send-keys 'docker-compose up' C-m
tmux split-window -v
tmux send-keys 'tail -f logs/development.log' C-m
tmux attach -t backend"

Recovery and maintenance

SSH connections drop. Processes freeze. Sessions accumulate. tmux provides straightforward recovery mechanisms for these inevitable issues:

# Check if your tmux session is still running
ssh user@remote-server 'tmux ls'

# If it exists, reattach
ssh -t user@remote-server 'tmux attach -t your-session'

# If server is unresponsive but tmux is running
ssh user@remote-server 'tmux kill-session -t stuck-session'

When processes freeze within tmux, standard keyboard shortcuts provide escape routes:

# From within tmux
Ctrl-b ?      # View all commands
Ctrl-b d      # Detach from session
Ctrl-b x      # Kill current pane
Ctrl-b &      # Kill current window

Long-running sessions benefit from periodic maintenance. List clients and sessions to see what's active. Kill old sessions that are no longer needed. Monitor the tmux server's resource usage to ensure it isn't consuming unexpected memory or CPU:

# Check tmux server status
tmux list-clients
tmux list-sessions

# Clean up old sessions
tmux kill-session -t old-session

# Monitor tmux server resource usage
ps aux | grep tmux

That database migration completed successfully because tmux kept it running when the network dropped. The session persisted. The output was preserved. Reconnecting took seconds. Without tmux, that migration failure would have meant hours of cleanup, determining what state the database was in, deciding whether to restart or roll back, potentially corrupting data in the process. With tmux, the disconnection was irrelevant—an interruption to monitoring, not to the work itself.

This is tmux's fundamental value: it decouples your view of work from the work itself. Sessions persist independently of your connection to them. Processes continue regardless of network stability. Workspaces remain organised across crashes and restarts. The terminal interface becomes a window onto persistent infrastructure rather than the infrastructure itself.

The learning curve exists but isn't steep. Start with basic session management—creating sessions, detaching, reattaching. Add window management when you need multiple logical workspaces. Introduce pane splitting when you want to monitor multiple things simultaneously. The features reveal themselves as needs arise. You don't need to master everything immediately. You don't need elaborate configurations or complex workflows. Start with persistence and organisation. The rest follows naturally.

For remote work, tmux becomes essential infrastructure. For local development, it provides workspace organisation that survives terminal crashes. The combination—local tmux managing your development environment, remote tmux managing server infrastructure—creates resilience at both layers. Your local work stays organised. Your remote processes keep running. Network issues become interruptions rather than disasters. That peace of mind, alone, justifies the initial investment.