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 — strictly cheaper in agent turns than polling pane content via capture_pane or wait_for_text.

The composition pattern: send_keys a command that emits the signal on its exit, then wait_for_channel. The signal MUST fire on both success and failure paths or the wait will block until the timeout.

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

The ; status=$?; tmux wait-for -S NAME; exit $status idiom is the load-bearing safety contract — wait-for is edge-triggered, so a crash before the signal would deadlock until the wait’s timeout.

wait_for_channel

wait_for_channel

mutating tool

Block until a tmux wait-for channel is signalled.

Returns:

str

Use when the shell command can reliably emit the signal (single test runs, build scripts, dev-server boot, anything composable with ; status=$?; tmux wait-for -S name; exit $status).

Avoid when the signal cannot be guaranteed — for example, when the command might be killed externally. Use wait_for_text to poll for an output marker instead; state-polling is structurally safer than edge-triggered signalling for fragile commands.

Side effects: Blocks the call up to timeout seconds (default 30). Mandatory subprocess timeout — a crashed signaller raises ToolError rather than blocking indefinitely.

Parameters

Parameter	Type	Required	Default	Description
channel	str	yes	—	Channel name. Must match ^[A-Za-z0-9_.:-]{1,128}$.
timeout	float	no	30.0	Maximum seconds to wait. The underlying tmux wait-for has no built-in timeout — this wrapper enforces it via subprocess.run(timeout=...). Defaults to 30 seconds.
socket_name	str	no	—	tmux socket name.