tmux

name	tmux
description	Tmux terminal multiplexer commands and workflows. Use when managing tmux sessions, windows, panes, or capturing terminal output for debugging.

Tmux Controls

Testing TUI Applications

Use tmux to automate testing of terminal UI applications without manual interaction.

Basic TUI Test Pattern

# 1. Start app in detached session with specific size
tmux new-session -d -s test-app -x 100 -y 30 -c /path/to/cwd "my-tui-app 2>/tmp/app-stderr.log"
sleep 2  # Wait for app to initialize

# 2. Send input (keys, shortcuts, text)
tmux send-keys -t test-app 'C-r'      # Ctrl+R
tmux send-keys -t test-app Down       # Arrow key
tmux send-keys -t test-app 'search'   # Type text
tmux send-keys -t test-app Enter      # Enter key
sleep 0.3  # Wait for UI to update

# 3. Capture and verify output
tmux capture-pane -t test-app -p | grep "expected text"

# 4. Cleanup
tmux kill-session -t test-app 2>/dev/null

Common Key Sequences

# Control keys
tmux send-keys -t session 'C-c'       # Ctrl+C
tmux send-keys -t session 'C-r'       # Ctrl+R
tmux send-keys -t session 'C-l'       # Ctrl+L

# Special keys
tmux send-keys -t session Enter
tmux send-keys -t session Escape
tmux send-keys -t session Tab
tmux send-keys -t session BSpace      # Backspace
tmux send-keys -t session Up Down Left Right

# Text input (sent as-is, may arrive as single input event)
tmux send-keys -t session 'hello world'

Capturing Screen States

# Visible area only (no scrollback)
tmux capture-pane -t test-app -p

# With line numbers for debugging
tmux capture-pane -t test-app -p | cat -n

# First/last N lines
tmux capture-pane -t test-app -p | head -25
tmux capture-pane -t test-app -p | tail -15

# Filter to specific section
tmux capture-pane -t test-app -p | grep -A 10 "HEADER"

# With ANSI escape codes (verify colors/styling)
tmux capture-pane -t test-app -e -p | cat -v

# Get terminal dimensions
tmux display -t test-app -p '#{pane_width}x#{pane_height}'

Multi-Step Test Flow

#!/bin/bash
# Example: Test a picker UI with navigation and selection

tmux new-session -d -s test -x 100 -y 30 "my-app 2>/tmp/stderr.log"
sleep 2

echo "=== 1. Open picker ==="
tmux send-keys -t test 'C-r'
sleep 0.5
tmux capture-pane -t test -p | grep -A 5 "Search"

echo "=== 2. Navigate down ==="
tmux send-keys -t test Down
tmux send-keys -t test Down
sleep 0.3
tmux capture-pane -t test -p | grep "❯"  # Check cursor moved

echo "=== 3. Filter by typing ==="
tmux send-keys -t test 'filter-text'
sleep 0.3
tmux capture-pane -t test -p | grep -c "result"  # Count results

echo "=== 4. Select and verify ==="
tmux send-keys -t test Enter
sleep 0.5
tmux capture-pane -t test -p | grep "expected output"

# Check stderr for errors
echo "=== Errors ==="
cat /tmp/stderr.log

tmux kill-session -t test 2>/dev/null

Debugging Tips

# Log all stderr to file for debugging
tmux new-session -d -s test "app 2>/tmp/debug.log"

# Check what input was received (add logging to your app)
# In app: console.error(`INPUT: ${[...data].map(c => c.charCodeAt(0))}`)

# Verify ANSI codes are present (colors/bold)
tmux capture-pane -t test -e -p | grep "text" | cat -v
# Look for: ^[[1m (bold), ^[[38;2;R;G;Bm (RGB color)

# Compare before/after states
tmux capture-pane -t test -p > /tmp/before.txt
tmux send-keys -t test Down
sleep 0.3
tmux capture-pane -t test -p > /tmp/after.txt
diff /tmp/before.txt /tmp/after.txt

Listing Sessions, Windows, and Panes

tmux list-sessions -F '#{session_name}'
tmux list-windows -a -F '#{session_name}:#{window_index} #{window_name}'
tmux list-panes -a -F '#{session_name}:#{window_index}.#{pane_index} #{pane_id} #{pane_active} #{pane_current_command}'

Capturing Scrollback

Log Watching

# Last 2000 lines
tmux capture-pane -t agent:main.0 -p -S -2000 -J

# Search for errors
tmux capture-pane -t agent:main.0 -p -S -50000 -J | rg 'ERROR|FATAL'

Failure Triage

# Most recent READY
tmux capture-pane -t agent:main.0 -p -S -50000 -J | tac | rg -m1 'READY'

# Capture with 2 lines context
tmux capture-pane -t agent:main.0 -p -S -50000 -J | rg -C2 'failed|timeout'

Report Building

# Extract block between sentinels
tmux capture-pane -t agent:main.0 -p -S -50000 -J | rg -U -o 'BEGIN<<[\s\S]*?>>END'

Finding Panes by Content

# Find panes containing a keyword
tmux list-panes -a -F '#{session_name}:#{window_index}.#{pane_index}' | \
  xargs -I{} sh -c 'tmux capture-pane -t {} -p -S -5000 -J | rg -q "KEYWORD" && echo {}'

# Match by running command
tmux list-panes -a -F '#{pane_id} #{pane_current_command}' | rg '\s(node|python)$'

Creating Windows and Panes

# New window & split
tmux new-window -t agent -n work
tmux split-window -t agent:work -h

# Send keys to pane
tmux send-keys -t agent:work.0 'echo hello' C-m

capture-pane Flags Reference

Flag	Description
-t	Target pane (session:window.pane)
-p	Print to stdout
-S	Start line (negative = from end)
-J	Join wrapped lines
-e	Include escape sequences (colors)
-x	Width (with new-session)
-y	Height (with new-session)