# Tmux Orchestration

> 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.

- Skill: `majiayu000/tmux-orchestration` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/tmux-orchestration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/tmux-orchestration/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/tmux-orchestration

---


# 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

```bash
# 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

```bash
# 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:

```bash
# 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](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:

```bash
# 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"`