tmux-master

tmux Master

Overview

tmux is the backbone of parallel AI agent execution. Misconfigured sessions cause orphaned processes, lost output, and silent failures that waste entire execution waves.

Core principle: Every tmux operation must be targeted to a specific session, window, or pane by ID — never rely on "current" context in automated workflows.

Violating the letter of this process is violating the spirit of reliable automation.

The Iron Law

ALWAYS USE EXPLICIT TARGETS (-t session:window.pane). NEVER ASSUME CONTEXT.

Automated workflows run outside interactive shells. tmux commands without -t targets silently operate on the wrong pane or fail entirely. There are no exceptions.

No exceptions:

• "The session is obvious" → Explicit -t anyway
• "There's only one pane" → Panes get added; target explicitly
• "I'll fix the target later" → Fix it now; debugging wrong-pane issues is expensive

When to Use

This skill provides background knowledge for ANY tmux operation:

• Creating sessions, windows, or panes for parallel agents
• Managing layouts for multi-pane orchestration
• Sending commands to panes programmatically
• Polling pane output for readiness or completion
• Styling panes for visual differentiation
• Debugging tmux-related failures in CI or automation

Relevant contexts:

• taskMaestro wave execution with multiple parallel panes
• AI agent orchestration requiring isolated terminal environments
• Any workflow that spawns, monitors, or communicates with tmux panes

When NOT to Use

• Interactive tmux usage — Manual terminal multiplexing needs no formal process
• Single-pane workflows — If you only need one terminal, tmux adds no value
• Docker/container orchestration — Use container tools, not tmux, for process isolation

---

Phase 1: Session, Window, and Pane Lifecycle

1.1 Session Management

# Create a named session (detached)
tmux new-session -d -s "my-session"

# Create session with a specific starting directory
tmux new-session -d -s "my-session" -c "/path/to/project"

# List all sessions
tmux list-sessions

# Kill a specific session
tmux kill-session -t "my-session"

# Kill ALL sessions (use with caution)
tmux kill-server