# tmux.ControlClient

- **Module:** tmux
- **Package:** github.com/libtmux/libtmux-go/tmux
- **Language:** Go
- **Kind:** struct
- **Source:** https://github.com/libtmux/libtmux-go/blob/52968a3181c1c9e6d1b26c565d4b170968ae61c0/tmux/control_client.go#L39
- **Page:** https://libtmux.org/en/go/latest/reference/tmux-controlclient/

ControlClient is one attached tmux control-mode process. Create one with [Server.OpenControl]. Concurrent Cmd, Wait, and close calls are supported; exactly one caller may execute NextNotification at a time.

It is the low-level handle: it carries commands and notifications on one
client and can [ControlClient.Reconnect], but records do not run through it.
[Session.OpenControl] returns a [Connection] instead, whose lanes the
sessions, windows and panes obtained from it use for their own commands.

## Members

- `ClientName` (method): ClientName returns the tmux-assigned identity captured during registration.
- `Server` (method): Server returns the server handle used to start the control client.
- `Session` (method): Session returns the materialized session selected during startup.
- `Wait` (method): Wait blocks until the control process exits or ctx ends. It does not close the notification queue; callers may drain final notifications before Close.
- `CloseContext` (method): CloseContext starts idempotent control-client shutdown and waits within ctx. The context bounds only the wait: an already-ended context still starts shutdown, and a later call may resume waiting for the same close.
- `Close` (method): Close stops the control process and releases its notification queue. It is safe to call concurrently and more than once.
- `Reconnect` (method): Reconnect registers a replacement on the last attached session observed at a reply boundary, then closes the receiver. Failed replacement setup does not initiate receiver shutdown. If shutdown fails, Reconnect returns the live replacement with that error; the caller owns every non-nil result. A receiver whose stream ended cleanly can recover from its last observation. Commands are never replayed.
- `Cmd` (method): Cmd executes one safely encoded tmux command through the control client. It requires exactly one reply frame and returns [ErrControlReplyCount] otherwise. Use [ControlClient.Call] for aliases that may produce zero or multiple frames.
- `Call` (method): Call executes one safely encoded tmux command and returns all its reply frames. Cancellation after writing returns [ErrOutcomeUnknown] with the context error while the client drains through the boundary before reuse. A transport failure returns any frames proven before the failure together with [ErrOutcomeUnknown].
- `NextNotification` (method): NextNotification returns the next ordered control-mode notification. Exactly one caller may execute it at a time. Close releases the queue and makes subsequent reads report os.ErrClosed, drained through queued notifications first. Natural process exit before a caller asked to close instead reports [ErrControlStreamLost] - most often because the server the underlying tmux client was attached to exited - naming the tmux exit reason when one was sent. A terminal reader error follows notifications queued before that failure. A full bounded queue likewise drains before reporting [ControlNotificationOverflowError].
- `Notifications` (method): Notifications returns an iterator over what tmux says without being asked: pane output, and the events behind [ControlNotification].