majiayu000 Tmux Orchestration
Overview
Direct tmux control for interactive terminal processes. No wrappers, no dependencies beyond tmux itself.
Prerequisite: User must be in a tmux session. Ask them to run tmux new-session -s shared if not.
When to Use
Use tmux orchestration when:
- Interactive debugging - Step through code with pdb/node inspect, observe state, decide next action
- REPL exploration - Iterative code refinement beyond simple execution
- Another Claude instance - Fresh perspective, specialized focus, or reasoning verification
- Observable long-running processes - Dev servers where logs need monitoring while working
Do NOT use when:
- Simple command execution suffices (use Bash directly)
- No interactivity needed (output is final, no decisions based on it)
Core Commands
# Create pane (horizontal split), returns immediately
tmux split-window -h
# Create pane with command
tmux split-window -h "python3"
# Send text to pane (with Enter)
tmux send-keys -t 1 "print('hello')" Enter
# Send text without Enter
tmux send-keys -t 1 "partial input"
# Capture pane output
tmux capture-pane -t 1 -p
# Capture last N lines
tmux capture-pane -t 1 -p -S -20
# List panes (see what exists)
tmux list-panes
# Kill pane
tmux kill-pane -t 1
# Send Ctrl+C
tmux send-keys -t 1 C-c
Pane Targeting
After split-window, new pane becomes active. Use -t to target specific panes:
-t 0- pane 0 (usually the original)-t 1- pane 1 (first split)-t session:window.pane- fully qualified
Check current panes: tmux list-panes -F "#{pane_index}: #{pane_current_command}"
Wait for Output to Stabilize
# Simple: just wait
sleep 2 && tmux capture-pane -t 1 -p
# Better: wait until output stops changing
LAST=""; for i in {1..30}; do
CURRENT=$(tmux capture-pane -t 1 -p | tail -20)
[ "$CURRENT" = "$LAST" ] && break
LAST="$CURRENT"; sleep 0.5
done
tmux capture-pane -t 1 -p
Critical Pattern: Launch Shell First
Direct command launch loses output on error (pane closes). Launch shell first:
# CORRECT
tmux split-window -h "zsh"
tmux send-keys -t 1 "python script.py" Enter
# WRONG - if script crashes, pane dies, output lost
tmux split-window -h "python script.py"
Workflows
For detailed patterns, see references/workflows.md.
Interactive Debugging: shell → start pdb → send n/s/p commands → capture state → decide next step
Claude-to-Claude: shell → claude → send focused prompt → wait → capture response → integrate
REPL Exploration: shell → start repl → send expression → capture → refine
Session Setup
If user isn't in tmux, they need to start a session first:
# User runs in their terminal:
tmux new-session -s shared
# Then Claude can create panes they'll see
To check if in tmux: [ -n "$TMUX" ] && echo "in tmux" || echo "not in tmux"