/tmux

name: tmux
description: Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output.
metadata:
  {
    "emoji": "🧵",
    "requires": { "bins": ["tmux"] }
  }

tmux Session Control

Control tmux sessions by sending keystrokes and reading output. Essential for managing long-running terminal sessions.

When to Use

✅ **USE this skill when:**

• Monitoring sessions in tmux
• Sending input to interactive terminal applications
• Scraping output from long-running processes in tmux
• Navigating tmux panes/windows programmatically
• Checking on background work in existing sessions

When NOT to Use

❌ **DON'T use this skill when:**

• Running one-off shell commands → run them directly
• Starting new background processes → use shell backgrounding
• Non-interactive scripts → run them directly
• The process isn't in tmux
• You need to create a new tmux session → use `tmux new-session`

Common Commands

List Sessions

tmux list-sessions
tmux ls

Capture Output

# Last 20 lines of pane
tmux capture-pane -t shared -p | tail -20

# Entire scrollback
tmux capture-pane -t shared -p -S -

# Specific pane in window
tmux capture-pane -t shared:0.0 -p

Send Keys

# Send text (doesn't press Enter)
tmux send-keys -t shared "hello"

# Send text + Enter
tmux send-keys -t shared "y" Enter

# Send special keys
tmux send-keys -t shared Enter
tmux send-keys -t shared Escape
tmux send-keys -t shared C-c          # Ctrl+C
tmux send-keys -t shared C-d          # Ctrl+D (EOF)
tmux send-keys -t shared C-z          # Ctrl+Z (suspend)

Window/Pane Navigation

# Select window
tmux select-window -t shared:0

# Select pane
tmux select-pane -t shared:0.1

# List windows
tmux list-windows -t shared

Session Management

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

# Kill session
tmux kill-session -t sessionname

# Rename session
tmux rename-session -t old new

Sending Input Safely

For interactive TUIs, split text and Enter into separate sends to avoid paste/multiline edge cases:

tmux send-keys -t shared -l -- "Please apply the patch in src/foo.ts"
sleep 0.1
tmux send-keys -t shared Enter

Check All Sessions Status

for s in $(tmux list-sessions -F '#{session_name}'); do
  echo "=== $s ==="
  tmux capture-pane -t $s -p 2>/dev/null | tail -5
done

Notes

• Use `capture-pane -p` to print to stdout (essential for scripting)
• `-S -` captures entire scrollback history
• Target format: `session:window.pane` (e.g., `shared:0.0`)
• Sessions persist across SSH disconnects