tmux Control Patterns

Reliable patterns for programmatic tmux interaction. The #1 source of bugs is targeting — follow these rules strictly.

Golden Rules

1. Use unique IDs for targeting: %N (pane), @N (window), $NAME (session) — never bare indexes
2. Use wait-for instead of sleep for synchronization
3. Pass commands to new-window/split-window directly — avoid send-keys to freshly created panes (race condition)
4. Always use -d (detached) with new-window and split-window — never steal focus from the user's active window
5. Verify targets exist before sending — use list-panes -a to check panes, list-windows for windows, has-session for sessions
6. Use full binary paths in commands sent to panes — the pane's environment may differ from yours

Targeting

The format is SESSION:WINDOW.PANE. All three parts are optional but be explicit.

Discover targets first — always