Ep 4: tmux — The Bedrock of Persistent Sessions

A terminal multiplexer that runs on any Unix server. Its detach/attach capabilities ensure Agent sessions keep running indefinitely.

What is tmux?

tmux is not a terminal emulator. It is a terminal multiplexer that runs inside a terminal emulator.

Key differences:

• Terminal Emulator (Ghostty/iTerm2/Warp): Renders graphics, manages windows, and is a desktop application for macOS/Linux.
• Terminal Multiplexer (tmux): Manages sessions, is purely command-line based, and runs on the server.

┌─────────────────────────────────────┐
│ Terminal Emulator (Ghostty/iTerm2)   │
│  ┌───────────────────────────────┐  │
│  │ tmux session                  │  │
│  │  ┌──────────┬──────────────┐  │  │
│  │  │ Agent 1  │ Agent 2      │  │  │
│  │  │ (pane)   │ (pane)       │  │  │
│  │  └──────────┴──────────────┘  │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘

Installation

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# CentOS/RHEL/Fedora
sudo yum install tmux
# or
sudo dnf install tmux

# Arch Linux
sudo pacman -S tmux

# Verify installation
tmux -V
# Output: tmux 3.5a (or later)

Operating System Support

Three-Tier Structure

tmux is organized into: session → window → pane

graph TB
    S[tmux server] --> SE1[Session: agent-1]
    S --> SE2[Session: agent-2]
    S --> SE3[Session: review]

    SE1 --> W1[Window 0]
    W1 --> P1[Pane: claude]
    W1 --> P2[Pane: logs]

    SE2 --> W2[Window 0]
    W2 --> P3[Pane: claude]
    SE2 --> W4[Window 1]
    W4 --> P4[Pane: tests]

    style S fill:#ff6b6b,color:#fff
    style SE1 fill:#4a9eff,color:#fff
    style P1 fill:#2ecc71,color:#fff

• Session: An independent workspace. Continues running after detaching; restores upon attaching.
• Window: Tabs within a session. A session can have multiple windows.
• Pane: Splits within a window. A window can have multiple panes.

Key Operations

Session Lifecycle

stateDiagram-v2
    [*] --> Created: tmux new -s agent
    Created --> Attached: Auto-attach
    Attached --> Detached: Ctrl+b d
or close terminal
    Detached --> Attached: tmux attach -t agent
    Attached --> Attached: Normal usage
    Detached --> Running: Continues in background
    Running --> Attached: tmux attach -t agent
    Running --> Destroyed: tmux kill-session
    Attached --> Destroyed: tmux kill-session
    Destroyed --> [*]

    note right of Running
        Agent continues running
        SSH disconnects don't affect it
        Closing your laptop doesn't affect it
    end note

Agent Interaction Mechanism

tmux provides the most powerful command-line level control over Agents:

flowchart TB
    subgraph Control Modes
        A[tmux send-keys
Command Injection]
        B[tmux CLI
Session Management]
        C[Socket File
IPC]
        D[Config File
~/.tmux.conf]
    end

    subgraph Agent Sessions
        E[Session: agent-1]
        F[Session: agent-2]
        G[Session: agent-N]
    end

    A -->|Send command to pane| E
    A -->|Send command to pane| F
    B -->|Create/Kill/List| E
    B -->|Create/Kill/List| G
    C -->|Direct Socket IPC| E
    D -->|Load at startup| H[tmux server]

    style A fill:#2ecc71,color:#fff
    style B fill:#4a9eff,color:#fff
    style C fill:#ff6b6b,color:#fff

send-keys Automation Example:

#!/bin/bash
# Batch start Claude Code Agents

# Create 3 sessions
tmux new-session -d -s research -d 'claude'
tmux new-session -d -s coding -d 'claude'
tmux new-session -d -s review -d 'claude'

# Send command to research agent
tmux send-keys -t research '/gsd-research-phase 1' Enter

# Send command to coding agent
tmux send-keys -t coding '/gsd-execute-phase 1' Enter

# Send command to review agent
tmux send-keys -t review '/gsd-code-review' Enter

echo "3 Agents started. Use 'tmux attach -t <name>' to view."

Recommended Configuration

Essential entries for ~/.tmux.conf:

# Mouse support (scroll, click to switch panes, resize)
set -g mouse on

# Large buffer (Agents output a lot)
set -g history-limit 100000

# Show session name in status bar
set -g status-left '#[fg=green]#S #[default]'

# Show time in status bar
set -g status-right '#[fg=yellow]%H:%M#[default]'

# 256-color + TrueColor support
set -g default-terminal "screen-256color"
set -ga terminal-overrides ",xterm-256color:Tc"

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

# Intuitive split keys
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

# Window numbering starts at 1
set -g base-index 1
setw -g pane-base-index 1

# Reduce ESC delay (critical for Vim users)
set -sg escape-time 0

Pros & Cons

Best Use Cases

• Running Agents on remote servers (Core use case)
• Multi-Agent parallelism + script automation
• Maintaining sessions through SSH disconnects
• Used as an "inner layer" inside Ghostty or iTerm2