tmux-orchestration

majiayu000 的头像作者 majiayu000

通过 tmux 控制交互式终端进程 - 启动 CLI 应用程序、发送输入、捕获输出、等待完成。当任务需要交互式调试(pdb、节点检查)、REPL 探索、长时间运行的可观察进程或生成另一个 Claude 实例以进行独立分析或第二意见时,应使用此技能。

📖 中文导读:通过 tmux 控制交互式终端进程 - 启动 CLI 应用程序、发送输入、捕获输出、等待完成。当任务需要交互式调试(pdb、节点检查)、REPL 探索、长时间运行的可观察进程或生成另一个 Claude 实例以进行独立分析或第二意见时,应使用此技能。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

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"