# tmux

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

- Author: Laurynas Keturakis
- Repository: laulauland/dotfiles
- Version: 20260119140624
- Stars: 5
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/laulauland/dotfiles
- Web: https://mule.run/skillshub/@@laulauland/dotfiles~tmux:20260119140624

---

---
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
#!/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

```bash
# 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

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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) |