tmux-orchestration
通过 tmux 控制交互式终端进程 - 启动 CLI 应用程序、发送输入、捕获输出、等待完成。当任务需要交互式调试(pdb、node inspect)、REPL 探索、长时间运行的可观察进程或生成另一个 Claude 实例进行独立分析或提供第二意见时,应使用此技能。
name: tmux-orchestration description: Control interactive terminal processes via tmux - launch CLI applications, send input, capture output, wait for completion. This skill should be used when tasks require interactive debugging (pdb, node inspect), REPL exploration, long-running observable processes, or spawning another Claude instance for independent analysis or second opinions.
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"