Wait for channel¶

tmux’s wait-for command exposes named, server-global channels that clients can signal and block on. These give agents an explicit synchronization primitive for custom shell composition. For the common “run this shell command and report the result” workflow, prefer run_command, which wraps this pattern and returns exit status plus output.

The composition pattern: send_keys a command followed by ; tmux wait-for -S NAME, then call wait_for_channel. Shell ; semantics fire the second statement whether the first succeeds or fails, so the edge-triggered signal never deadlocks the agent on a crashed command.

send_keys(
    pane_id="%1",
    keys="pytest; tmux wait-for -S tests_done",
)
wait_for_channel("tests_done", timeout=60)

The ; tmux wait-for -S NAME suffix is the load-bearing safety contract — wait-for is edge-triggered, so a crash before the signal would deadlock until the wait’s timeout. The shell separator ; runs the next statement unconditionally, so the signal fires on both success and failure paths.

The payload deliberately does not append exit $? — in an interactive shell that exits the shell itself, taking single-pane sessions down with it. If exit-status preservation matters and the command fits the standard one-shot shape, use run_command.