Tmux

tmux

Use tmux for interactive terminal sessions and terminal UI verification. For ordinary commands, use bash: supported owner-bound calls can run in the background explicitly with wait: { kind: "background" } or automatically after their foreground observation budget expires. Use tmux when you need a separate interactive terminal, not merely because a command outlives a tool call. Background tasks remain bound to their owning Atomic session.

On Windows, use psmux, the native Windows tmux-compatible multiplexer. psmux automatically provides the tmux alias, so keep using the tmux commands below; no command changes are needed.

When this skill is invoked, first confirm tmux is available before running tmux commands (command -v tmux or tmux -V; on Windows PowerShell, Get-Command tmux). If tmux is not found, tell the user to install tmux on macOS/Linux or psmux on Windows, depending on their OS, using one of the options below.

Installation

Choose the install path that matches the host OS and package manager.

macOS/Linux tmux

Package managers are preferred when available:

brew install tmux

To build official tmux from a release tarball, install libevent 2.x, ncurses, a C compiler, make, pkg-config, and yacc or bison, then run:

./configure && make
sudo make install

To build the latest tmux from version control, also install autoconf and automake:

git clone https://github.com/tmux/tmux.git
cd tmux
sh autogen.sh
./configure && make
sudo make install

Windows psmux

psmux installs psmux, pmux, and tmux; this skill should continue to use tmux in examples and scripts.

winget install psmux
cargo install psmux
scoop bucket add psmux https://github.com/psmux/scoop-psmux
scoop install psmux
choco install psmux

Alternatively, download the latest .zip from GitHub Releases and add it to PATH, or build from source with Cargo:

git clone https://github.com/psmux/psmux.git
cd psmux
cargo build --release

Basics

tmux ls
tmux list-windows -t shared
tmux list-panes -t shared:0
tmux capture-pane -t shared:0.0 -p
tmux capture-pane -t shared:0.0 -p -S -

Target format: session:window.pane, e.g. shared:0.0.

Send input

Literal text, then Enter:

tmux send-keys -t shared:0.0 -l -- "Please continue"
tmux send-keys -t shared:0.0 Enter

Special keys:

tmux send-keys -t shared:0.0 C-c
tmux send-keys -t shared:0.0 C-d
tmux send-keys -t shared:0.0 Escape

Use -l -- for arbitrary text. Split text and Enter to avoid paste/newline surprises.

Sessions

tmux new-session -d -s worker
tmux rename-session -t old new
tmux kill-session -t worker

Prompt checks

tmux capture-pane -t worker-3 -p | tail -20
tmux capture-pane -t worker-3 -p | rg "proceed|permission|Yes|No|❯"

Approve/select only when the prompt is understood:

tmux send-keys -t worker-3 -l -- "y"
tmux send-keys -t worker-3 Enter

QA/testing and analysis

Prefer read-only inspection before sending input. These commands are especially useful for diagnosing interactive tests, stuck agents, TUI apps, and long-running CLI workflows.

Discover every pane with useful state:

tmux list-panes -a -F '#{session_name}:#{window_index}.#{pane_index} #{pane_current_command} #{pane_current_path} active=#{pane_active} dead=#{pane_dead}'

Capture output for assertions or log review:

tmux capture-pane -t shared:0.0 -p -S -          # full scrollback
tmux capture-pane -t shared:0.0 -p -S - -J       # join wrapped lines
tmux capture-pane -t shared:0.0 -p -S -1000      # recent output only
tmux capture-pane -t shared:0.0 -p -e -S -1000   # include escape/color codes for TUI debugging

Inspect what a pane is running:

tmux display-message -p -t shared:0.0 '#{pane_current_command} #{pane_current_path} pid=#{pane_pid}'
tmux show-messages

Stream pane output to a file for later analysis without interrupting the process:

tmux pipe-pane -t shared:0.0 -o 'cat >> /tmp/tmux-pane-shared-0-0.log'

Coordinate tests or scripts with tmux signals:

tmux wait-for qa-ready      # wait
tmux wait-for -S qa-ready   # signal

Keep failed commands visible and label panes for easier reports:

tmux set-option -t shared remain-on-exit on
tmux select-pane -t shared:0.0 -T "api-tests"

If a tmux-compatible implementation does not support a specific format variable or option, fall back to the simpler list-panes, capture-pane, and send-keys forms above.

Helpers

• scripts/find-sessions.sh: discover sessions.
• scripts/wait-for-text.sh: wait until pane output contains text.

Notes

• capture-pane -p prints to stdout for scripts.
• -S - captures full scrollback.
• tmux sessions persist across SSH disconnects.