tmux - SKILL.md Agent Skill

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

tmux Skill

Use tmux only when you need an interactive TTY. Prefer the shell tool for non-interactive tasks.

When to use

Running interactive CLIs (python REPL, node REPL, etc.)
Long-running processes that need monitoring
Parallel task execution with multiple sessions
Any command that requires a persistent terminal

Quickstart (isolated socket)

SOCKET_DIR="${TMPDIR:-/tmp}/chatdock-tmux"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/chatdock.sock"
SESSION=chatdock-main

# Create a new session
tmux -S "$SOCKET" new -d -s "$SESSION" -n shell

# Send commands
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'echo Hello World' Enter

# Capture output
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200

After starting a session, always provide monitor commands to the user:

To monitor:
  tmux -S "$SOCKET" attach -t "$SESSION"
  tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200

Socket convention

Default socket: $TMPDIR/chatdock-tmux/chatdock.sock
Use a consistent socket path for all ChatDock sessions

Targeting panes

Target format: session:window.pane (defaults to :0.0)

# List all sessions
tmux -S "$SOCKET" list-sessions

# List all panes
tmux -S "$SOCKET" list-panes -a

Sending input safely

# Literal text (preferred)
tmux -S "$SOCKET" send-keys -t target -l -- "$cmd"

# With Enter key
tmux -S "$SOCKET" send-keys -t target -- "ls -la" Enter

# Control keys
tmux -S "$SOCKET" send-keys -t target C-c   # Ctrl+C
tmux -S "$SOCKET" send-keys -t target C-d   # Ctrl+D

Watching output

# Capture recent history (last 200 lines)
tmux -S "$SOCKET" capture-pane -p -J -t target -S -200

# Watch for a specific pattern (poll every 0.5s)
while ! tmux -S "$SOCKET" capture-pane -p -t target | grep -q "pattern"; do
  sleep 0.5
done
echo "Pattern found!"

Running Python REPLs

For Python REPLs, set PYTHON_BASIC_REPL=1 to avoid readline issues:

tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'PYTHON_BASIC_REPL=1 python3 -q' Enter

Parallel execution (multiple agents)

SOCKET="${TMPDIR:-/tmp}/multi-agent.sock"

# Create multiple sessions
for i in 1 2 3; do
  tmux -S "$SOCKET" new-session -d -s "task-$i"
done

# Launch tasks
tmux -S "$SOCKET" send-keys -t task-1 "cd /project1 && npm test" Enter
tmux -S "$SOCKET" send-keys -t task-2 "cd /project2 && npm test" Enter
tmux -S "$SOCKET" send-keys -t task-3 "cd /project3 && npm test" Enter

# Poll for completion
for sess in task-1 task-2 task-3; do
  if tmux -S "$SOCKET" capture-pane -p -t "$sess" -S -3 | grep -q "\\$"; then
    echo "$sess: DONE"
  else
    echo "$sess: Running..."
  fi
done

Cleanup

# Kill a specific session
tmux -S "$SOCKET" kill-session -t "$SESSION"

# Kill all sessions on socket
tmux -S "$SOCKET" kill-server

# Remove socket file
rm -f "$SOCKET"

Windows/WSL Note

This skill requires macOS or Linux. On Windows, use WSL and install tmux inside WSL.