name: automating-tmux-windows description: Automates terminal sessions in tmux windows using MCP tools. Use when launching background processes, monitoring builds/servers, sending commands to debuggers (pdb/gdb), interacting with CLI prompts, using interactive commands or commands that require sudo, or orchestrating parallel tasks across multiple terminal sessions. triggers: tmux, terminal automation, background process, interactive commands, sudo, debugger, pdb, gdb, long-running process, server monitoring

Automating tmux Windows

Control tmux windows programmatically: create windows, send commands, capture output, and manage processes. Each window gets full screen space for easier output tracking.

Note: These tools are provided by the orchestrator MCP server, which also includes AI CLI tools (see ai-orchestration skill).

Recommended: Use Subagent for Context Efficiency

To save context in the main conversation, delegate tmux operations to the tmux-runner subagent:

# Instead of calling tmux tools directly, use Task tool:
Task(
    subagent_type="tmux-runner",
    description="Run npm build",
    prompt="Run 'npm run build' in the project directory. Return success/failure and any errors.",
    model="haiku"  # Fast and cheap for simple commands
)

When to use subagent:

• Simple build/test commands
• Any command where you just need pass/fail + output
• Commands that don't need real-time monitoring

When to use direct tmux tools:

• Long-running servers you need to monitor over time
• Complex interactive debugging sessions
• When you need the window to persist across multiple operations

Quick Reference

Window Identifiers

Always use the window ID returned by tmux_new_window (e.g., "@3"). These IDs:

• Never change when other windows are created or killed
• Persist until the window itself is destroyed
• Are the only reliable way to reference windows across operations

Window names are visible in the tmux status bar for easy identification.

Standard Workflow

# 1. Create window - SAVE THE RETURNED ID
# Can pass any command directly - non-shell commands are auto-wrapped in a shell
window_id = mcp__orchestrator__tmux_new_window(command="npm run build", name="build")  # Returns "@3"

# 2. Wait for completion
mcp__orchestrator__tmux_wait_idle(target=window_id, idle_seconds=2.0)  # Returns "idle" or "timeout"

# 3. Get output
output = mcp__orchestrator__tmux_capture(target=window_id, lines=50)

# 4. Optionally switch to window to view it
mcp__orchestrator__tmux_select(target=window_id)

# 5. Cleanup
mcp__orchestrator__tmux_kill(target=window_id)

File-Based Output Workflow

For commands that write to a file (cleaner than capturing pane output):

# Single call: run command, wait for completion, return file contents
# Use __OUTPUT_FILE__ placeholder - it gets replaced with a random /tmp path
result = mcp__orchestrator__tmux_run_and_read(
    command="my-tool --output __OUTPUT_FILE__",
    name="my-task",
    timeout=300
)

Key differences from tmux_new_window:

• Does NOT spawn a shell wrapper (command runs directly)
• Waits for window to close (command exit) instead of idle detection
• Returns file contents instead of pane capture
• Auto-generates safe temp file path (replaces __OUTPUT_FILE__ placeholder)
• Auto-cleans up window and output file

Use cases:

• CLI tools with -o or --output flags that accept a path argument
• Wrapper scripts that write results to a specified path

Parallel Windows

Create multiple windows for parallel tasks:

# Create named windows - commands run directly
logs_window = mcp__orchestrator__tmux_new_window(command="tail -f /var/log/app.log", name="logs")
work_window = mcp__orchestrator__tmux_new_window(command="cd ~/project && make", name="work")

# Capture from both
logs = mcp__orchestrator__tmux_capture(target=logs_window, lines=100)
output = mcp__orchestrator__tmux_capture(target=work_window, lines=50)

Interactive Commands

For commands requiring input (sudo, prompts, debuggers):

# Start interactive session
window_id = mcp__orchestrator__tmux_new_window(command="sudo apt update", name="sudo")

# Wait for password prompt
mcp__orchestrator__tmux_wait_idle(target=window_id, idle_seconds=1, timeout=10)

# Send password (if needed)
mcp__orchestrator__tmux_send(target=window_id, text="password")

# Wait for completion
mcp__orchestrator__tmux_wait_idle(target=window_id, idle_seconds=2, timeout=120)

Window Navigation

• Use tmux_select to switch to a window programmatically
• User can navigate with Ctrl+b n (next) / Ctrl+b p (previous)
• Window names appear in tmux status bar

Tool Parameters

tmux_new_window

tmux_run_and_read

The __OUTPUT_FILE__ placeholder is replaced with an auto-generated /tmp/tmux_output_<uuid>.txt path.

tmux_wait_idle

tmux_capture

Safety

• Cannot kill own window (server prevents this)
• Use mcp__orchestrator__tmux_interrupt to stop runaway processes
• Check is_claude field in mcp__orchestrator__tmux_list to identify your window
• Always store and reuse the window ID from mcp__orchestrator__tmux_new_window
• Target validation prevents command injection via window IDs