tmux

mcp

Serve one tmux server to Model Context Protocol clients, built on the [tmux module] and the [Go MCP SDK].

$ go install github.com/libtmux/libtmux-go/mcp/cmd/libtmux-mcp@latest

Releases are numbered 0.1.N, and each release increments N. The API is not settled: any release may change or remove exported identifiers, and the changelog marks each break. Pin an exact version to avoid one.

Contents — Quick start · Connect another client · Choose which tmux it drives · See an agent work · Run work and wait for it · The tools · Limiting what a client can do · Settings · The pane it runs in · Known limits · Troubleshooting · An agent-shaped program · Embedding it · Packages · What it leaves out · Support and status · See also

Quick start

You need Go 1.26 or newer and tmux 3.3a or newer on PATH. The install command above puts libtmux-mcp in GOBIN when that is set, and in $(go env GOPATH)/bin otherwise.

An MCP client launches it as a subprocess and speaks to it over stdin and stdout. Closing the client ends the MCP process and its owned connections; tmux sessions remain running. If your shell cannot find libtmux-mcp, add that directory to PATH.

The Python server installs a command of the same name. Run command -v libtmux-mcp to see which one comes first, and libtmux-mcp -version to name this one.

claude mcp add: tell Claude Code about it

$ claude mcp add tmux -- libtmux-mcp

Claude Code starts each server it lists, to check that it connects:

$ claude mcp list

libtmux-mcp -doctor: check what it reaches

$ libtmux-mcp -doctor

It answers without a client in the way, and prints something like this:

libtmux-mcp doctor

tmux: 3.6 (requires 3.3a or newer) socket: /tmp/tmux-1000/default (from tmux-choice) holds: nothing — no tmux server is running on that socket (not a fault; tmux starts one when something asks it to) caller: not running inside a tmux pane

Then ask the client for something only tmux can do, such as "create a tmux session called demo and tell me what panes it has".

Connect another client

Each client takes the same command and the same flags. Connect an MCP client on libtmux.org covers startup and shutdown.

codex mcp add: Codex CLI

$ codex mcp add tmux -- libtmux-mcp

gemini mcp add: Gemini CLI

$ gemini mcp add tmux libtmux-mcp

claude_desktop_config.json: Claude Desktop

Claude Desktop starts its servers without your shell's PATH, so give it the path command -v libtmux-mcp prints. Flags go in args and the environment in env:

{

"mcpServers": { "tmux": { "command": "/path/to/libtmux-mcp", "args": ["-socket-name", "my-application"], "env": {"LIBTMUX_TOOLSETS": "inspect,manage,execute"} } } }

Choose which tmux it drives

The choice is made once, when the server starts. A client cannot change it afterwards. Settings lists the other flags, and the contract has the precedence rules.

-socket-name: pick a socket by name

With no flag and neither LIBTMUX_SOCKET_PATH nor LIBTMUX_SOCKET set, the server passes tmux no socket, so tmux picks the server. Started inside tmux, that is the server you are in. Started elsewhere, it is tmux's default socket, which holds the sessions you already have, and an agent given it can change them. A named socket keeps an agent apart from them:

$ claude mcp add tmux -- libtmux-mcp -socket-name my-application

Tools target the selected socket and still run with your user's authority; tool selection is not confinement.

Once it has made a session, watch it work from another terminal:

$ tmux -L my-application attach

To drive the tmux you use every day from outside it, name that socket. tmux calls its usual one default:

$ claude mcp add tmux -- libtmux-mcp -socket-name default

A workspace that tmux-workspace load -L project built lives on the socket project. To let a client read it and change nothing:

$ claude mcp add tmux \

-e LIBTMUX_TOOLSETS=inspect \ -- libtmux-mcp -socket-name project

-socket-path and -binary: an exact socket and tmux

-socket-path names the socket by its absolute path, and -binary names the tmux executable. -doctor reports what a choice selects:

$ libtmux-mcp \

-doctor \ -socket-path /tmp/my-application.sock

The environment makes the same choices when no flag is given, which is how a client's configuration sets them. LIBTMUX_SOCKET_PATH names a socket path and LIBTMUX_SOCKET a socket name, and the path wins when both are set:

$ LIBTMUX_SOCKET=my-application libtmux-mcp -doctor

See an agent work

These are the calls examples/agent-workflow makes to run work in a pane beside its own, and what came back. Cursor tokens are left out, and each reply shows only the fields that answer the call:

→ split_window {"direction":"right","pane_id":"%0","percent":40}

← {"paneId":"%1"} → paste_text {"enter":true,"pane_id":"%1","text":"if sleep 1; then printf 'agent-workflow-%s\\n' ready; else printf 'agent-workflow-%s\\n' failed; fi"} ← {"bytes":97} → wait_for_text {"pane_id":"%1","patterns":["agent-workflow-ready"],"stop":["agent-workflow-failed"],"timeout":30} ← {"found":true,"matched":"agent-workflow-ready","outcome":"matched"} → run_shell_command {"command":"printf 'bounded work\\n'","pane_id":"%1","timeout":30} ← {"exit_status":0,"output":["bounded work"],"timed_out":false}

The example prints these with -trace, and its page has the command. The agent drives tmux directly, so nothing is copy-pasted out of a terminal, and waiting for a server to come up is one call.

Run work and wait for it

For one tmux send-keys, shelling out is shorter. The server earns its keep once the agent has to wait, watch, inspect, or leave your terminal alone.

A dev server printing its port, a test run finishing, or a deploy log settling turns a shell-out into a polling loop. That loop reads the shell's echo of its own command and reports success before anything happened.

split_window: make room beside your pane

split_window adds a pane and returns its id. A new pane is given time to start, so run_shell_command can follow at once.

The trace splits %0 to the right with "percent":40 and gets back {"paneId":"%1"}.

wait_for_text: wait for what a pane prints

wait_for_text watches a pane and returns when a pattern appears, or when a stop pattern appears first. capture_since returns what a pane wrote since the last look.

The trace waits for agent-workflow-ready and names agent-workflow-failed as the stop pattern. It gets "outcome":"matched".

A wait longer than the ceiling is shortened, and the reply says so. The ceiling is LIBTMUX_MCP_WAIT_MAX_SECONDS.

If the pane goes away mid-wait, the reply's outcome is paneDied and lines holds what it wrote first. If only the output stream ends and the pane is alive, it is streamLost. The contract has the rest.

run_shell_command: run a command and read its exit status

run_shell_command waits for the command and returns its exit status and output, without reading the screen at all. send_keys and paste_text send input and return.

The trace runs a command that prints "bounded work" and gets back "exit_status":0.

run_shell_command refuses a pane linked with others by synchronize-panes, because one exit status cannot describe several panes.

Keep reads small

Other parts of the design exist because an agent's context and its turn are the scarce resources.

• Reads are bounded. Captures keep the newest lines asked for and say what they left out. Searches have fixed limits, which the contract lists.
• One call can make several reads. call_read_tools_batch answers a list of inspect calls with one row each.
• Checking is not capturing. The listing tools report what exists without reading what any pane shows. snapshot_pane returns a pane's metadata and content together.

The tools

The tools come in toolsets. A toolset is a named group of tools, and it is what an operator grants or withholds:

• inspect reads tmux and what panes show, and changes nothing.
• manage rearranges what exists: it renames, resizes, selects, and moves.
• execute creates sessions, windows, and panes, and sends input to them.
• teardown kills sessions, windows, and panes, and clears scrollback.

| manage | [`move_