# libtmux_mcp.tools.wait_for_tools.wait_for_channel

- **Module:** libtmux_mcp.tools.wait_for_tools
- **Package:** libtmux-mcp
- **Language:** Python
- **Kind:** function
- **Source:** https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/wait_for_tools.py#L145
- **Page:** https://libtmux.org/en/py/stable/mcp/reference/libtmux_mcp-tools-wait_for_tools-wait_for_channel/

```
libtmux_mcp.tools.wait_for_tools.wait_for_channel(
    channel: str,
    timeout: float = 30.0,
    socket_name: str | None = None,
) -> str
```

Block until a tmux [`wait-for`](/en/tmux/latest/manual/wait-for/) channel is signalled.

This is the AUTHORED-output synchronisation primitive: the channel
only fires because your own composed shell command signals it.
Reserve ``wait_for_text`` for output you did not author.

Agents can compose this with ``send_keys`` to turn shell-side
milestones into explicit synchronisation points:

```text
send_keys(
    "pytest; tmux wait-for -S tests_done",
    pane_id=...,
)
wait_for_channel("tests_done", timeout=60)
```

Shell ``;`` semantics fire [`wait-for -S`](/en/tmux/latest/manual/wait-for/) whether the command
succeeded or failed, so the edge-triggered signal never deadlocks
on a crash. Do NOT chain ``exit $status`` after the signal — in an
interactive shell that exits the shell itself, which destroys
single-pane sessions. Exit-status preservation in interactive
shells is out-of-scope; inspect the captured output for
command-specific success markers.

## Parameters

- `channel` (`str`): Channel name. Must match ``^[A-Za-z0-9_.:-]{1,128}$``.
- `timeout` (`float`): Maximum seconds to wait. The underlying ``tmux wait-for`` has
no built-in timeout — this wrapper enforces it by killing the
tmux child, which also happens if the call is cancelled.
Defaults to 30 seconds. Capped by the same server wait ceiling
as ``wait_for_text``; an over-large value is not an error, the
wait returns at the ceiling and the confirmation message names
the timeout that was actually enforced.
- `socket_name` (`str | None`): tmux socket name.

## Returns

str
    Confirmation message naming the channel and the timeout
    actually enforced.

## Raises

- [`ExpectedToolError`](https://libtmux-mcp.git-pull.com/reference/api/utils/#libtmux_mcp._utils.ExpectedToolError): On timeout, invalid channel name, tmux error, or when the tmux
server disappeared during the wait — ``tmux wait-for`` exits 0
for a clean server shutdown exactly as it does for a real
signal, so that case is detected by re-probing the server and
reported rather than passed off as success.