Tmux

tmux

Complete tmux management for terminal multiplexing.

Core Concepts

┌─────────────────────────────────────────────────────────────┐
│ SERVER (one per socket)                                     │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ SESSION ($0, $1, ...)                                 │  │
│  │  ┌─────────────────┐  ┌─────────────────┐            │  │
│  │  │ WINDOW (@0)     │  │ WINDOW (@1)     │  ...       │  │
│  │  │  ┌────┬────┐   │  │  ┌────────────┐ │            │  │
│  │  │  │PANE│PANE│   │  │  │   PANE     │ │            │  │
│  │  │  │ %0 │ %1 │   │  │  │    %2      │ │            │  │
│  │  │  └────┴────┘   │  │  └────────────┘ │            │  │
│  │  └─────────────────┘  └─────────────────┘            │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

• Server: Background process managing all state
• Session ($id): Named container of windows, persists after detach
• Window (@id): Tab-like container of panes within a session
• Pane (%id): Individual terminal within a window
• Client: Terminal attached to a session

Router

Default Key Bindings (Prefix: C-b)

Session

Window

Pane

Copy Mode

Quick Reference

# Session
tmux new -s name              # Create named session
tmux attach -t name           # Attach to session
tmux ls                       # List sessions
tmux kill-session -t name     # Kill session

# Window
tmux new-window -n name       # Create named window
tmux select-window -t :N      # Go to window N
tmux rename-window name       # Rename current window

# Pane
tmux split-window -h          # Split horizontal
tmux split-window -v          # Split vertical
tmux select-pane -t :.N       # Go to pane N
tmux resize-pane -D 5         # Resize down 5 lines

# Info
tmux list-keys                # All key bindings
tmux info                     # Server info

Safety Rules

• Confirm before kill: Always confirm before kill-session, kill-window, kill-pane
• Check attachments: Before killing, check if session has active clients
• Preserve work: Warn if panes have running processes
• Config backup: Before editing ~/.tmux.conf, suggest backup

Confirmation Policy

Read-only (always OK):

• tmux ls, list-sessions, list-windows, list-panes
• tmux info, show-options, display-message
• tmux list-keys, list-buffers

Requires confirmation:

• kill-session, kill-window, kill-pane
• kill-server
• Editing ~/.tmux.conf
• send-keys to panes (can affect running processes)

Environment Variables

Check if inside tmux: [ -n "$TMUX" ]

Troubleshooting

tmux Skill

Complete tmux terminal multiplexer management for AI agents.

What This Does

Enables full tmux control:

• Session lifecycle (create, attach, detach, kill)
• Window management (create, rename, navigate, close)
• Pane operations (split, resize, move, zoom)
• Copy mode and buffers
• Configuration and key bindings
• Scripting and automation

Entry Points

References

• references/session-management.md - Session lifecycle
• references/window-management.md - Window operations
• references/pane-management.md - Pane operations
• references/layouts.md - Layout management
• references/copy-mode.md - Copy/paste
• references/configuration.md - Config and options
• references/keybindings.md - Key binding management
• references/scripting.md - Automation and scripting

Requirements

• tmux 3.0+ installed
• Unix-like OS (Linux/macOS/WSL)

Configuration

tmux configuration via ~/.tmux.conf and options.

Config File

# Default location
~/.tmux.conf

# Alternative locations
~/.config/tmux/tmux.conf    # XDG compliant
/etc/tmux.conf              # System-wide

# Reload config
tmux source-file ~/.tmux.conf

# Bind reload to key
bind-key r source-file ~/.tmux.conf \; display-message "Config reloaded"

Option Types

Common Options

General

# Set prefix key
set-option -g prefix C-a
unbind-key C-b
bind-key C-a send-prefix

# Start windows/panes at 1 (not 0)
set-option -g base-index 1
set-window-option -g pane-base-index 1

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

# History limit
set-option -g history-limit 50000

# Enable mouse
set-option -g mouse on

# Escape time (for vim)
set-option -sg escape-time 0

# Repeat time for key bindings
set-option -g repeat-time 500

Display

# Terminal colors
set-option -g default-terminal "tmux-256color"
set-option -ga terminal-overrides ",xterm-256color:Tc"

# Focus events (for vim)
set-option -g focus-events on

# Status bar position
set-option -g status-position top

# Display time for messages
set-option -g display-time 3000

# Display time for pane numbers
set-option -g display-panes-time 3000

Key Modes

# Vi mode in copy
set-window-option -g mode-keys vi

# Vi mode in status line (command prompt)
set-option -g status-keys vi

Status Line

# Status bar colors
set-option -g status-style "bg=#282a36,fg=#f8f8f2"

# Left side
set-option -g status-left-length 50
set-option -g status-left "[#S] "

# Right side
set-option -g status-right-length 100
set-option -g status-right "#H | %Y-%m-%d %H:%M"

# Window status
set-window-option -g window-status-format " #I:#W "
set-window-option -g window-status-current-format " #I:#W* "
set-window-option -g window-status-current-style "bg=blue,fg=white"

# Separator
set-window-option -g window-status-separator ""

# Update interval (seconds)
set-option -g status-interval 5

Status Line Variables

Pane Borders

# Border colors
set-option -g pane-border-style "fg=#444444"
set-option -g pane-active-border-style "fg=#00ff00"

# Show pane titles in border
set-option -g pane-border-status top
set-option -g pane-border-format " #{pane_index}: #{pane_title} "

Window Options

# Automatic rename
set-window-option -g automatic-rename on
set-window-option -g automatic-rename-format "#{pane_current_command}"

# Activity monitoring
set-window-option -g monitor-activity on
set-option -g visual-activity on

# Aggressive resize
set-window-option -g aggressive-resize on

View/Modify Options

# Show all global options
tmux show-options -g

# Show all window options
tmux show-window-options -g

# Show specific option
tmux show-options -g status-style

# Show option value only
tmux show-options -gv status-style

Conditional Configuration

# Check tmux version
%if #{>=:#{version},3.2}
    # tmux 3.2+ settings
    set-option -g extended-keys on
%endif

# Check if SSH session
%if #{SSH_CONNECTION}
    set-option -g status-right "SSH | #H"
%endif

# Check OS
%if #{==:#{host},Darwin}
    # macOS settings
    bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"
%endif

User Options

Custom options prefixed with @:

# Set user option
set-option -g @my-setting "value"

# Read user option
tmux show-options -gv @my-setting

Environment Variables

# Update environment on attach
set-option -g update-environment "SSH_AUTH_SOCK SSH_AGENT_PID"

# Set environment variable
set-environment -g MY_VAR "value"

# Unset
set-environment -g -u MY_VAR

Example Configuration

# ~/.tmux.conf

# --- General ---
set-option -g prefix C-a
unbind-key C-b
bind-key C-a send-prefix

set-option -g base-index 1
set-window-option -g pane-base-index 1
set-option -g renumber-windows on
set-option -g history-limit 50000
set-option -g mouse on
set-option -sg escape-time 0

# --- Display ---
set-option -g default-terminal "tmux-256color"
set-option -ga terminal-overrides ",xterm-256color:Tc"
set-option -g focus-events on

# --- Keys ---
set-window-option -g mode-keys vi
set-option -g status-keys vi

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

# Easy splits
bind-key | split-window -h -c "#{pane_current_path}"
bind-key - split-window -v -c "#{pane_current_path}"

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

# --- Status ---
set-option -g status-position top
set-option -g status-style "bg=#1e1e2e,fg=#cdd6f4"
set-option -g status-left "[#S] "
set-option -g status-right "#H | %H:%M"
set-window-option -g window-status-current-style "bg=#89b4fa,fg=#1e1e2e"

# --- Borders ---
set-option -g pane-border-style "fg=#45475a"
set-option -g pane-active-border-style "fg=#89b4fa"

# --- Clipboard ---
bind-key -T copy-mode-vi v send-keys -X begin-selection
bind-key -T copy-mode-vi y send-keys -X copy-selection-and-cancel

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

Copy Mode

Copy mode allows text selection, searching, and copying from pane history.

Enter/Exit Copy Mode

# Enter copy mode
tmux copy-mode

# Key binding: C-b [

# Exit copy mode: q or Escape

Navigation (Vi Mode)

Set vi mode in config:

set-window-option -g mode-keys vi

Navigation (Emacs Mode)

Default mode or set explicitly:

set-window-option -g mode-keys emacs

Selection

Vi Mode

# Start selection
Space          # Start character-wise selection
v              # Start character-wise selection (alternative)
V              # Start line-wise selection
C-v            # Start block (rectangle) selection

# Modify selection
o              # Move cursor to other end of selection

# Copy selection
Enter          # Copy and exit
y              # Copy and exit (alternative)

Emacs Mode

# Start selection
C-Space        # Start selection

# Copy selection
M-w            # Copy and exit

Copy to System Clipboard

macOS

# In .tmux.conf
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"
bind-key -T copy-mode-vi Enter send-keys -X copy-pipe-and-cancel "pbcopy"

Linux (X11)

# In .tmux.conf
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -selection clipboard"

Linux (Wayland)

# In .tmux.conf
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "wl-copy"

Paste

# Paste most recent buffer
tmux paste-buffer

# Key binding: C-b ]

# Choose buffer to paste
tmux choose-buffer

# Key binding: C-b =

Buffer Management

# List buffers
tmux list-buffers

# Key binding: C-b #

# Show buffer content
tmux show-buffer
tmux show-buffer -b buffer0

# Save buffer to file
tmux save-buffer -b buffer0 ~/clipboard.txt

# Load file to buffer
tmux load-buffer ~/clipboard.txt

# Delete buffer
tmux delete-buffer
tmux delete-buffer -b buffer0

# Set buffer content
tmux set-buffer "text content"

Search

In Copy Mode

# Forward search
/pattern       # Vi mode
C-s pattern    # Emacs mode

# Backward search
?pattern       # Vi mode
C-r pattern    # Emacs mode

# Next/previous match
n / N          # Vi mode
C-s / C-r      # Emacs mode (repeat)

Incremental Search

# Enable in config
set-window-option -g incremental-search on

History Limit

# Set scrollback buffer size (lines)
set-option -g history-limit 50000

# Default is 2000

Mouse Support

# Enable mouse in config
set-option -g mouse on

# With mouse enabled:
# - Click to position cursor
# - Drag to select
# - Right-click to paste
# - Scroll wheel navigates history

Copy Mode Configuration

# ~/.tmux.conf

# Vi keys
set-window-option -g mode-keys vi

# Start selection with v
bind-key -T copy-mode-vi v send-keys -X begin-selection

# Rectangle select with C-v
bind-key -T copy-mode-vi C-v send-keys -X rectangle-toggle

# Copy with y
bind-key -T copy-mode-vi y send-keys -X copy-selection-and-cancel

# Don't exit copy mode on mouse release
bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-selection -x

Scripting Copy Mode

# Capture pane content
tmux capture-pane -p                    # Print to stdout
tmux capture-pane -S -100               # Last 100 lines
tmux capture-pane -p > pane-content.txt # Save to file

# Capture with escape sequences (colors)
tmux capture-pane -e -p

# Capture entire history
tmux capture-pane -S - -E - -p

# Copy specific text to buffer
tmux set-buffer "specific text"

# Send buffer content to command
tmux save-buffer - | grep "pattern"

Quick Copy Recipes

Copy Last Command Output

# Bind to key
bind-key C-c capture-pane -S -1 -E -1 \; save-buffer - \; delete-buffer

Copy Visible Pane

tmux capture-pane -p

Copy URL Under Cursor

Use plugins like tmux-urlview or tmux-open:

# With tmux-urlview
# Press u in copy mode to open urlview

Key Bindings

Customize tmux key bindings.

Binding Syntax

# Basic binding
bind-key key command

# With prefix (default)
bind-key -T prefix key command

# Without prefix (root table)
bind-key -T root key command

# In copy mode
bind-key -T copy-mode-vi key command
bind-key -T copy-mode key command

# Repeat without prefix
bind-key -r key command

Key Tables

List Bindings

# All bindings
tmux list-keys

# Specific table
tmux list-keys -T prefix
tmux list-keys -T copy-mode-vi

# Key binding: C-b ?

Unbind

# Unbind in prefix table
unbind-key key

# Unbind in specific table
unbind-key -T root key
unbind-key -T copy-mode-vi key

# Unbind all
unbind-key -a

Common Rebindings

Change Prefix

# Use C-a instead of C-b
set-option -g prefix C-a
unbind-key C-b
bind-key C-a send-prefix

# Double-tap prefix to send to app
bind-key a send-prefix

Vim-Style Navigation

# Pane navigation
bind-key h select-pane -L
bind-key j select-pane -D
bind-key k select-pane -U
bind-key l select-pane -R

# Window navigation
bind-key -r C-h select-window -t :-
bind-key -r C-l select-window -t :+

Vim-Style Resize

# Resize panes (repeatable)
bind-key -r H resize-pane -L 5
bind-key -r J resize-pane -D 5
bind-key -r K resize-pane -U 5
bind-key -r L resize-pane -R 5

Better Splits

# More intuitive split keys
bind-key | split-window -h -c "#{pane_current_path}"
bind-key - split-window -v -c "#{pane_current_path}"
bind-key _ split-window -v -c "#{pane_current_path}"

# Retain current path in new window
bind-key c new-window -c "#{pane_current_path}"

Quick Actions

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

# Toggle synchronize panes
bind-key S set-window-option synchronize-panes

# Quick session switch
bind-key s choose-tree -Zs

# Kill pane without confirm
bind-key x kill-pane

# Kill window without confirm
bind-key X kill-window

Copy Mode Bindings

# Vi-style copy mode
set-window-option -g mode-keys vi

# Selection
bind-key -T copy-mode-vi v send-keys -X begin-selection
bind-key -T copy-mode-vi C-v send-keys -X rectangle-toggle
bind-key -T copy-mode-vi V send-keys -X select-line

# Copy
bind-key -T copy-mode-vi y send-keys -X copy-selection-and-cancel
bind-key -T copy-mode-vi Enter send-keys -X copy-selection-and-cancel

# System clipboard (macOS)
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"

# System clipboard (Linux)
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -selection clipboard"

# Search
bind-key -T copy-mode-vi / command-prompt -i -p "Search:" "send-keys -X search-forward-incremental \"%%%\""

Mouse Bindings

# Enable mouse
set-option -g mouse on

# Don't exit copy mode on mouse release
unbind-key -T copy-mode-vi MouseDragEnd1Pane

# Right click to paste
bind-key -T root MouseDown3Pane paste-buffer

Root Table Bindings

Bindings that work without prefix:

# Alt+arrow pane navigation
bind-key -T root M-Left select-pane -L
bind-key -T root M-Right select-pane -R
bind-key -T root M-Up select-pane -U
bind-key -T root M-Down select-pane -D

# Alt+number window switch
bind-key -T root M-1 select-window -t :1
bind-key -T root M-2 select-window -t :2
bind-key -T root M-3 select-window -t :3

Repeatable Bindings

Use -r for bindings that can repeat without pressing prefix again:

# Resize with repeat
bind-key -r H resize-pane -L 2
bind-key -r J resize-pane -D 2
bind-key -r K resize-pane -U 2
bind-key -r L resize-pane -R 2

# Navigate windows with repeat
bind-key -r n next-window
bind-key -r p previous-window

# Set repeat time (ms)
set-option -g repeat-time 500

Conditional Bindings

# Different behavior based on zoom state
bind-key z if-shell "tmux list-panes -F '#F' | grep -q Z" \
    "resize-pane -Z" \
    "resize-pane -Z"

# Toggle based on option
bind-key m if-shell "tmux show-options -w | grep -q 'monitor-activity on'" \
    "set-window-option monitor-activity off" \
    "set-window-option monitor-activity on"

Run Commands

# Run shell command
bind-key T run-shell "date"

# Run in popup (tmux 3.2+)
bind-key G display-popup -E "lazygit"
bind-key F display-popup -E "fzf"

# Run and capture output
bind-key W run-shell "tmux list-windows | wc -l | xargs tmux display-message"

Send Keys

# Send literal keys
bind-key C-l send-keys C-l  # Clear screen

# Send key sequence
bind-key C-k send-keys "clear" Enter

Display Bindings

# Show all bindings
bind-key ? list-keys

# Show specific binding
# tmux list-keys | grep "key"

Complete Example

# ~/.tmux.conf keybindings section

# Prefix
set-option -g prefix C-a
unbind-key C-b
bind-key C-a send-prefix

# Reload
bind-key r source-file ~/.tmux.conf \; display-message "Reloaded"

# Splits
bind-key | split-window -h -c "#{pane_current_path}"
bind-key - split-window -v -c "#{pane_current_path}"

# Navigation (vim)
bind-key h select-pane -L
bind-key j select-pane -D
bind-key k select-pane -U
bind-key l select-pane -R

# Resize (vim, repeatable)
bind-key -r H resize-pane -L 5
bind-key -r J resize-pane -D 5
bind-key -r K resize-pane -U 5
bind-key -r L resize-pane -R 5

# Windows
bind-key -r n next-window
bind-key -r p previous-window
bind-key c new-window -c "#{pane_current_path}"

# Copy mode
bind-key -T copy-mode-vi v send-keys -X begin-selection
bind-key -T copy-mode-vi y send-keys -X copy-selection-and-cancel

# Quick actions
bind-key S set-window-option synchronize-panes
bind-key x kill-pane
bind-key X kill-window

# Popups (tmux 3.2+)
bind-key g display-popup -E -w 80% -h 80% "lazygit"

Layout Management

Layouts control how panes are arranged within a window.

Built-in Layouts

Apply Layout

# Apply specific layout
tmux select-layout even-horizontal
tmux select-layout even-vertical
tmux select-layout main-horizontal
tmux select-layout main-vertical
tmux select-layout tiled

# Cycle through layouts
# Key binding: C-b Space

# Previous layout
tmux select-layout -o

Main Pane Size

For main-horizontal and main-vertical layouts:

# Set main pane height (for main-horizontal)
tmux set-window-option main-pane-height 60%

# Set main pane width (for main-vertical)
tmux set-window-option main-pane-width 60%

# Set in cells instead of percentage
tmux set-window-option main-pane-height 30
tmux set-window-option main-pane-width 100

Custom Layouts

Layouts can be saved and restored using layout strings:

# Get current layout string
tmux list-windows -F "#{window_layout}"

# Apply custom layout string
tmux select-layout "layout-string-here"

Layout string format: checksum,width x height,position,pane-info...

Layout Examples

IDE Layout (main + 2 side)

# Create panes
tmux split-window -h -p 30
tmux split-window -v -t :.1

# Or apply main-vertical
tmux select-layout main-vertical
tmux set-window-option main-pane-width 70%

┌──────────────────┬──────────┐
│                  │          │
│      Main        │  Side 1  │
│      (70%)       │          │
│                  ├──────────┤
│                  │  Side 2  │
└──────────────────┴──────────┘

Dashboard (2x2 grid)

tmux split-window -v
tmux split-window -h
tmux select-pane -t :.0
tmux split-window -h
tmux select-layout tiled

┌──────────┬──────────┐
│   Pane   │   Pane   │
│    0     │    1     │
├──────────┼──────────┤
│   Pane   │   Pane   │
│    2     │    3     │
└──────────┴──────────┘

Horizontal Stack

tmux split-window -v
tmux split-window -v
tmux select-layout even-vertical

┌─────────────────────┐
│       Pane 0        │
├─────────────────────┤
│       Pane 1        │
├─────────────────────┤
│       Pane 2        │
└─────────────────────┘

Monitor Layout (1 big + 3 small)

tmux split-window -h -p 40
tmux split-window -v -t :.1
tmux split-window -v -t :.2

┌──────────────┬─────────┐
│              │  Pane 1 │
│              ├─────────┤
│    Pane 0    │  Pane 2 │
│    (main)    ├─────────┤
│              │  Pane 3 │
└──────────────┴─────────┘

Persist Layout

Save and restore layouts in .tmux.conf:

# Save a layout
LAYOUT=$(tmux list-windows -F "#{window_layout}")
echo "select-layout $LAYOUT" >> ~/.tmux-layouts/ide.conf

# Restore
tmux source-file ~/.tmux-layouts/ide.conf

Automatic Layout on Window Size

# Re-apply layout when terminal resizes
set-hook -g client-resized 'select-layout tiled'

Scripting Layouts

#!/bin/bash
# Create development layout

create_dev_layout() {
    local session=$1
    local window=$2

    # Main editor (left 60%)
    # File tree (top right 40%, height 30%)
    # Terminal (bottom right)

    tmux split-window -h -t $session:$window -p 40
    tmux split-window -v -t $session:$window.1 -p 70

    # Set names
    tmux select-pane -t $session:$window.0 -T "Editor"
    tmux select-pane -t $session:$window.1 -T "Files"
    tmux select-pane -t $session:$window.2 -T "Terminal"
}

# Usage
create_dev_layout "dev" 0

Other Layouts

Pip (Picture-in-Picture)

Small pane overlaying main:

# Create popup (tmux 3.2+)
tmux display-popup -E "htop"

Balanced Split

Equal-sized panes regardless of count:

# After creating panes
tmux select-layout tiled

Pane Management

Panes are individual terminal areas within a window.

Split Panes

# Horizontal split (left | right)
tmux split-window -h

# Vertical split (top / bottom)
tmux split-window -v

# Split with specific size (percentage)
tmux split-window -h -p 30   # 30% width
tmux split-window -v -p 20   # 20% height

# Split with specific size (lines/columns)
tmux split-window -h -l 50   # 50 columns
tmux split-window -v -l 10   # 10 lines

# Split with command
tmux split-window -h htop

# Split in specific directory
tmux split-window -h -c ~/projects

# Key bindings:
# C-b %   Split horizontal
# C-b "   Split vertical

Navigate Panes

# By direction
tmux select-pane -U   # Up
tmux select-pane -D   # Down
tmux select-pane -L   # Left
tmux select-pane -R   # Right

# By index
tmux select-pane -t :.0
tmux select-pane -t :.1

# Last pane
tmux select-pane -l

# Next pane (cycle)
tmux select-pane -t :.+

# Key bindings:
# C-b Up/Down/Left/Right   Navigate
# C-b o                    Cycle panes
# C-b q                    Show pane numbers (then press number)
# C-b ;                    Last pane

Resize Panes

# Resize by direction
tmux resize-pane -U 5    # Up 5 lines
tmux resize-pane -D 5    # Down 5 lines
tmux resize-pane -L 10   # Left 10 columns
tmux resize-pane -R 10   # Right 10 columns

# Resize to percentage
tmux resize-pane -x 50%  # 50% width
tmux resize-pane -y 30%  # 30% height

# Resize to specific size
tmux resize-pane -x 80   # 80 columns
tmux resize-pane -y 20   # 20 lines

# Zoom pane (toggle fullscreen)
tmux resize-pane -Z

# Key bindings:
# C-b z                   Toggle zoom
# C-b C-Up/Down/L/R       Resize (hold Ctrl)
# C-b M-Up/Down/L/R       Resize by 5 (hold Alt)

Move/Swap Panes

# Swap with previous/next
tmux swap-pane -U
tmux swap-pane -D

# Swap with specific pane
tmux swap-pane -t :.2

# Rotate panes
tmux rotate-window         # Clockwise
tmux rotate-window -D      # Counter-clockwise

# Move pane to another window
tmux move-pane -t :2

# Join pane from another window
tmux join-pane -s :2.0     # Source from window 2, pane 0

# Break pane to new window
tmux break-pane

# Key bindings:
# C-b {       Swap with previous
# C-b }       Swap with next
# C-b C-o     Rotate panes
# C-b !       Break pane to window

Kill Pane

Requires confirmation if pane has running process.

# Kill current pane
tmux kill-pane

# Kill specific pane
tmux kill-pane -t :.2

# Kill all except current
tmux kill-pane -a

# Key binding: C-b x (with confirmation)

Pane Info

# List panes
tmux list-panes

# Detailed format
tmux list-panes -F "#{pane_index}: #{pane_current_command} [#{pane_width}x#{pane_height}]"

# Show pane ID
tmux display-message -p "#{pane_id}"

# Check pane activity
tmux list-panes -F "#{pane_index}: #{pane_current_command} #{?pane_dead,DEAD,}"

Pane Options

# Set pane border style
tmux set-option pane-border-style "fg=gray"
tmux set-option pane-active-border-style "fg=green"

# Set pane title
tmux select-pane -T "My Pane Title"

# Display pane titles
tmux set-option pane-border-status top

Synchronize Panes

Send input to all panes simultaneously:

# Toggle synchronization
tmux set-window-option synchronize-panes on
tmux set-window-option synchronize-panes off

# Useful for:
# - Running same command on multiple servers
# - Testing in parallel

Mark Pane

# Mark pane (for swap/join operations)
tmux select-pane -m

# Clear mark
tmux select-pane -M

# Swap with marked pane
tmux swap-pane

Respawn Pane

# Respawn dead pane with same command
tmux respawn-pane

# Respawn with different command
tmux respawn-pane "htop"

# Kill existing process and respawn
tmux respawn-pane -k "new-command"

Pane Dimensions

# Get pane dimensions
tmux display-message -p "#{pane_width}x#{pane_height}"

# Get all pane info
tmux list-panes -F "#{pane_index}: #{pane_width}x#{pane_height} at #{pane_left},#{pane_top}"

Scripting Example

#!/bin/bash
# Create IDE-like layout

SESSION="ide"

tmux new-session -d -s $SESSION -c ~/project

# Create panes: editor (main), terminal (bottom), sidebar (right)
tmux split-window -v -p 20 -t $SESSION:0   # Bottom terminal
tmux split-window -h -p 25 -t $SESSION:0.0  # Right sidebar

# Name panes
tmux select-pane -t $SESSION:0.0 -T "Editor"
tmux select-pane -t $SESSION:0.1 -T "Sidebar"
tmux select-pane -t $SESSION:0.2 -T "Terminal"

# Send commands
tmux send-keys -t $SESSION:0.0 'nvim .' Enter
tmux send-keys -t $SESSION:0.1 'tree -L 2' Enter

# Focus main editor pane
tmux select-pane -t $SESSION:0.0

tmux attach -t $SESSION

Scripting & Automation

Programmatic tmux control for automation and scripting.

Target Syntax

Target format: session:window.pane

# Session only
tmux send-keys -t mysession "command"

# Session and window (by index)
tmux send-keys -t mysession:2 "command"

# Session and window (by name)
tmux send-keys -t mysession:editor "command"

# Full target with pane
tmux send-keys -t mysession:2.1 "command"

# Current session
tmux send-keys -t :2 "command"

# Current window
tmux send-keys -t :.1 "command"

# Using IDs
tmux send-keys -t $0      # Session ID
tmux send-keys -t @2      # Window ID
tmux send-keys -t %5      # Pane ID

Send Keys

# Send text
tmux send-keys -t target "echo hello"

# Send with Enter
tmux send-keys -t target "echo hello" Enter

# Send special keys
tmux send-keys -t target C-c          # Ctrl+C
tmux send-keys -t target C-d          # Ctrl+D
tmux send-keys -t target Escape       # Escape
tmux send-keys -t target Tab          # Tab
tmux send-keys -t target BSpace       # Backspace
tmux send-keys -t target Up Down      # Arrows

# Send literal text (no key interpretation)
tmux send-keys -t target -l "C-c is not Ctrl+C"

# Clear and send
tmux send-keys -t target C-c C-l "command" Enter

Capture Pane Content

# Capture visible pane
tmux capture-pane -t target -p

# Capture with history
tmux capture-pane -t target -p -S -100    # Last 100 lines
tmux capture-pane -t target -p -S -       # Entire history

# Capture range
tmux capture-pane -t target -p -S 10 -E 20

# Capture with escape sequences (colors)
tmux capture-pane -t target -p -e

# Save to file
tmux capture-pane -t target -p > output.txt

# Capture to buffer
tmux capture-pane -t target -b mybuffer
tmux save-buffer -b mybuffer output.txt

Display Message

# Display in status line
tmux display-message "Hello"

# Print to stdout
tmux display-message -p "Hello"

# With formats
tmux display-message -p "Session: #{session_name}"
tmux display-message -p "Window: #{window_index}:#{window_name}"
tmux display-message -p "Pane: #{pane_id} running #{pane_current_command}"

Format Strings

Common format variables:

# List with custom format
tmux list-sessions -F "#{session_id}: #{session_name} (#{session_windows} windows)"
tmux list-windows -F "#{window_index}: #{window_name}"
tmux list-panes -F "#{pane_index}: #{pane_current_command} [#{pane_width}x#{pane_height}]"

Conditionals in Formats

# Ternary
tmux list-windows -F "#{window_index}: #{?window_active,*,} #{window_name}"

# Comparison
tmux list-panes -F "#{?#{==:#{pane_current_command},vim},EDITING,OTHER}"

# Nested
tmux display-message -p "#{?#{>:#{window_width},100},Wide,#{?#{<:#{window_width},50},Narrow,Normal}}"

Wait and Synchronization

# Wait for channel
tmux wait-for channel-name

# Signal channel
tmux wait-for -S channel-name

# Lock channel
tmux wait-for -L channel-name
tmux wait-for -U channel-name    # Unlock

# Example: Wait for command completion
tmux send-keys -t target "long-command; tmux wait-for -S done" Enter
tmux wait-for done
echo "Command finished"

Run Shell Command

# Run and display output
tmux run-shell "date"

# Run in background
tmux run-shell -b "sleep 5; tmux display-message 'Done'"

# Run in specific pane
tmux run-shell -t target "pwd"

Hooks

# Session hooks
set-hook -g session-created 'display-message "Session created"'
set-hook -g session-closed 'run-shell "echo closed >> ~/tmux.log"'

# Window hooks
set-hook -g window-linked 'display-message "Window added"'
set-hook -g window-unlinked 'display-message "Window removed"'

# Pane hooks
set-hook -g pane-focus-in 'run-shell "echo #{pane_id} focused"'
set-hook -g pane-exited 'display-message "Pane exited"'

# Client hooks
set-hook -g client-attached 'refresh-client -S'
set-hook -g client-detached 'display-message "Client detached"'

# Alert hooks
set-hook -g alert-activity 'display-message "Activity in #{window_name}"'

# List hooks
tmux show-hooks -g

# Remove hook
set-hook -gu session-created

Scripting Examples

Development Environment

#!/bin/bash
SESSION="dev"
PROJECT_DIR="$HOME/project"

# Kill existing session
tmux kill-session -t $SESSION 2>/dev/null

# Create session with editor window
tmux new-session -d -s $SESSION -n editor -c $PROJECT_DIR

# Split for terminal
tmux split-window -t $SESSION:editor -v -p 30 -c $PROJECT_DIR

# Create server window
tmux new-window -t $SESSION -n server -c $PROJECT_DIR

# Create logs window with splits
tmux new-window -t $SESSION -n logs -c $PROJECT_DIR
tmux split-window -t $SESSION:logs -h -c $PROJECT_DIR

# Send commands
tmux send-keys -t $SESSION:editor.0 "nvim ." Enter
tmux send-keys -t $SESSION:server "npm run dev" Enter
tmux send-keys -t $SESSION:logs.0 "tail -f logs/app.log" Enter
tmux send-keys -t $SESSION:logs.1 "tail -f logs/error.log" Enter

# Select editor window
tmux select-window -t $SESSION:editor

# Attach
tmux attach -t $SESSION

Monitoring Dashboard

#!/bin/bash
SESSION="monitor"

tmux new-session -d -s $SESSION -n dashboard

# Create 2x2 grid
tmux split-window -t $SESSION -h
tmux split-window -t $SESSION:0.0 -v
tmux split-window -t $SESSION:0.2 -v

# Send monitoring commands
tmux send-keys -t $SESSION:0.0 "htop" Enter
tmux send-keys -t $SESSION:0.1 "watch -n 1 'df -h'" Enter
tmux send-keys -t $SESSION:0.2 "tail -f /var/log/syslog" Enter
tmux send-keys -t $SESSION:0.3 "nethogs" Enter

tmux attach -t $SESSION

CI/CD Runner

#!/bin/bash
# Run tests in tmux, wait for completion

SESSION="ci-$$"
tmux new-session -d -s $SESSION "npm test; tmux wait-for -S tests-done"
tmux wait-for tests-done

# Capture output
OUTPUT=$(tmux capture-pane -t $SESSION -p -S -)
tmux kill-session -t $SESSION

# Check result
if echo "$OUTPUT" | grep -q "PASS"; then
    echo "Tests passed"
    exit 0
else
    echo "Tests failed"
    echo "$OUTPUT"
    exit 1
fi

Remote Execution

#!/bin/bash
# Execute command on multiple servers

SERVERS=("server1" "server2" "server3")
COMMAND="uptime"
SESSION="multi-exec"

tmux new-session -d -s $SESSION

for i in "${!SERVERS[@]}"; do
    if [ $i -gt 0 ]; then
        tmux split-window -t $SESSION
        tmux select-layout -t $SESSION tiled
    fi
    tmux send-keys -t $SESSION:0.$i "ssh ${SERVERS[$i]} '$COMMAND'" Enter
done

# Synchronize input
tmux set-window-option -t $SESSION synchronize-panes on
tmux attach -t $SESSION

Control Mode

For programmatic integration:

# Start in control mode
tmux -C

# Or attach in control mode
tmux -C attach

# Outputs structured events like:
# %begin 1234567890 1 0
# %end 1234567890 1 0
# %window-add @1
# %session-changed $0 main

Session Management

Sessions are the top-level containers in tmux. They persist after detaching.

List Sessions

# List all sessions
tmux ls
tmux list-sessions

# Detailed format
tmux list-sessions -F "#{session_id}: #{session_name} (#{session_windows} windows) #{?session_attached,attached,detached}"

Create Session

# New session with default name
tmux new

# Named session
tmux new -s myproject

# Named session with initial window name
tmux new -s myproject -n editor

# Create detached (background)
tmux new -d -s background-job

# Create with initial command
tmux new -s logs -d 'tail -f /var/log/syslog'

# Create in specific directory
tmux new -s project -c ~/projects/myapp

Attach to Session

# Attach to most recent
tmux attach
tmux a

# Attach to named session
tmux attach -t myproject
tmux a -t myproject

# Attach and detach other clients
tmux attach -d -t myproject

# Create if doesn't exist, attach if does
tmux new -A -s myproject

Detach from Session

# From command line (inside tmux)
tmux detach

# Key binding: C-b d

# Detach other clients
tmux detach-client -a

Switch Session

# Switch to named session
tmux switch-client -t other-session

# Previous session
tmux switch-client -l

# Next/previous
tmux switch-client -n
tmux switch-client -p

# Key binding: C-b s (interactive chooser)
# Key binding: C-b ( / C-b ) (prev/next)

Rename Session

# Rename current session
tmux rename-session newname

# Rename specific session
tmux rename-session -t oldsession newsession

# Key binding: C-b $

Kill Session

Requires confirmation - kills all windows and panes.

# Kill named session
tmux kill-session -t myproject

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

# Kill all sessions except named
tmux kill-session -a -t keep-this

# Kill entire server (all sessions)
tmux kill-server

Session Info

# Show session options
tmux show-options -g

# Display session info
tmux display-message -p "Session: #{session_name}, Windows: #{session_windows}"

# Check if session exists
tmux has-session -t myproject && echo "exists"

Session Groups

Link windows across sessions:

# Create session in group
tmux new -s grouped -t existing-session

# Sessions in same group share windows

Hooks

# Run command on session creation
set-hook -g session-created 'display-message "New session created"'

# Run command on client attach
set-hook -g client-attached 'refresh-client -S'

Scripting Example

#!/bin/bash
# Create development environment

SESSION="dev"

# Create session with first window
tmux new-session -d -s $SESSION -n editor

# Create additional windows
tmux new-window -t $SESSION -n server
tmux new-window -t $SESSION -n logs

# Send commands to windows
tmux send-keys -t $SESSION:editor 'nvim .' Enter
tmux send-keys -t $SESSION:server 'npm run dev' Enter
tmux send-keys -t $SESSION:logs 'tail -f logs/*.log' Enter

# Attach to session
tmux attach -t $SESSION

Window Management

Windows are tabs within a session. Each window contains one or more panes.

List Windows

# List windows in current session
tmux list-windows

# List windows in specific session
tmux list-windows -t mysession

# Custom format
tmux list-windows -F "#{window_index}: #{window_name} #{?window_active,*,}"

# Key binding: C-b w (interactive chooser)

Create Window

# New window
tmux new-window

# Named window
tmux new-window -n mywindow

# Window at specific index
tmux new-window -t :3

# Window in specific session
tmux new-window -t mysession:

# Window with initial command
tmux new-window -n htop htop

# Window in specific directory
tmux new-window -c ~/projects

# Key binding: C-b c

Switch Window

# By index
tmux select-window -t :0
tmux select-window -t :1

# By name
tmux select-window -t :mywindow

# Last window
tmux select-window -l

# Next/previous
tmux next-window
tmux previous-window

# Key bindings:
# C-b 0-9     Go to window N
# C-b n       Next window
# C-b p       Previous window
# C-b l       Last window

Rename Window

# Rename current window
tmux rename-window newname

# Rename specific window
tmux rename-window -t :2 newname

# Key binding: C-b ,

Move Window

# Move to index
tmux move-window -t :5

# Swap windows
tmux swap-window -t :3

# Move to another session
tmux move-window -t othersession:

Link Window

Share a window across sessions:

# Link window from another session
tmux link-window -s source:2 -t target:

# Unlink window
tmux unlink-window -t :2

Kill Window

Requires confirmation - kills all panes in window.

# Kill current window
tmux kill-window

# Kill specific window
tmux kill-window -t :2

# Kill window by name
tmux kill-window -t :mywindow

# Key binding: C-b & (with confirmation)

Find Window

# Find window by name/content
tmux find-window searchterm

# Key binding: C-b f

Window Options

# Set window option
tmux set-window-option automatic-rename off

# Set for all windows
tmux set-window-option -g automatic-rename off

# Show window options
tmux show-window-options

Monitor Activity

# Enable activity monitoring
tmux set-window-option -t :2 monitor-activity on

# Enable silence monitoring (alert after N seconds of no output)
tmux set-window-option -t :2 monitor-silence 30

Window Styles

# Set window status style
tmux set-window-option window-status-style "fg=white,bg=black"

# Set active window style
tmux set-window-option window-status-current-style "fg=black,bg=green"

Scripting Example

#!/bin/bash
# Setup project windows

SESSION="project"

# Ensure session exists
tmux has-session -t $SESSION 2>/dev/null || tmux new-session -d -s $SESSION

# Create windows
tmux new-window -t $SESSION -n code
tmux new-window -t $SESSION -n terminal
tmux new-window -t $SESSION -n git

# Setup each window
tmux send-keys -t $SESSION:code 'nvim .' Enter
tmux send-keys -t $SESSION:git 'lazygit' Enter

# Select first window
tmux select-window -t $SESSION:0