Tmux

What tmux does

tmux provides an MCP-facing way to operate one tmux server and the terminal state managed by it. Its scope includes sessions, windows, panes, and the output rendered by those panes. The accompanying Go library represents these objects as typed values and includes the MCP package alongside the core tmux and workspace packages.

The server is suited to agents that share a terminal, automation that needs an interactive TTY, and tests that must exercise programs inside a real tmux environment. It can also work with a private tmux server, allowing a program to isolate its socket and configuration from an existing user session.

How it works

A caller connects through the MCP server to tmux-managed state. Commands can run in a window with a terminal, returning both the rendered screen content and the command's exit status. This makes it appropriate for terminal programs that behave differently when no TTY is present.

Sessions, windows, and panes can be listed individually. A snapshot reads the server once so callers can apply filters locally, while session searches can pass a tmux format filter for tmux to evaluate during the listing. Pane interaction supports writing input, with a newline representing the Enter key, then polling the visible screen until expected text appears.

Change notifications are available as tmux makes updates. Errors distinguish conditions such as a missing server, an ended pane, an unsupported tmux version, and a canceled or expired context.

Setup and configuration

The Go package is added with:

go get github.com/libtmux/libtmux-go/tmux@latest

It requires Go 1.26 or newer, tmux 3.3a or newer, and a Unix host. The tmux executable must be available on PATH for the quick-start configuration. With default server options, operations use the same tmux server as the regular tmux command.

For isolation, configure a distinct socket name and an empty configuration file. A private server can then be created for a run and terminated during cleanup, avoiding interference with an already-running tmux instance. Exact dependency versions should be pinned because the API can change between releases.

Tools and capabilities

• Run commands in terminal-backed tmux windows.
• Return rendered output and process exit status.
• List sessions, windows, and panes.
• Read a server snapshot and filter panes or other objects in Go.
• Ask tmux to filter sessions using its format expressions.
• Write input to panes and wait for text on the visible screen.
• Observe tmux changes through notifications.

Limitations and notes

The implementation supports Unix hosts and requires tmux 3.3a or newer. If the daemon is older than the supported version, the operation returns a version error without sending a command. A missing tmux server is reported as an error rather than as an empty listing.

The Go API is explicitly unsettled: exported identifiers may change or be removed in a later release. Pin an exact dependency version when repeatable builds depend on a stable API. Pane waiting polls the visible screen and returns the last screen it read when an error occurs; cancellation and deadlines return the context error.