tmux MCP server
Commit Nov 15, 2026Allows an AI client to drive a tmux server by managing sessions, windows, panes, and monitoring terminal output.
Also known as libtmux/libtmux-go, libtmux-mcp
- Stars
- 4
- Tools
- 4
- Downloads, 30 days
- —
- Latest version
- 0.0.1-alpha.4
- Last commit
- Nov 15, 2026
- License
- MIT
What is tmux MCP?
tmux allows an AI client to drive a tmux server by managing sessions, windows, panes, and monitoring terminal output. It exposes 4 tools, such as inspect, manage, execute.
Summary generated from the project's README
About tmux MCP server
Managing terminal sessions and monitoring command output from an AI client is what this server enables. It allows developers to connect Model Context Protocol clients like Claude Desktop, Claude Code, or Gemini CLI to a tmux server. By running as a subprocess, the server provides an interface for an agent to interact with tmux sessions, windows, and panes directly through stdin and stdout.
Users can control specific tmux instances by specifying a socket name, socket path, or using the default socket. The server organizes its capabilities into toolsets: inspect for reading data, manage for rearranging layouts, execute for creating and sending input, and teardown for cleaning up. This structure allows operators to limit an agent's authority by only enabling specific toolsets through environment variables. It requires Go 1.26 or newer and tmux 3.3a or newer to function.
What you can do with it
- 1Manage complex terminal layoutsA developer can have an AI client rearrange, resize, or rename existing tmux windows and panes.
- 2Restrict agent permissionsYou can configure the server so the AI can only view terminal information without the ability to execute commands.
Written from the project's README. Every use case is checked against a quote from it.
tmux MCP tools 4
Detected from the READMEinspectmanageexecuteteardown
Configuration
LIBTMUX_TOOLSETS
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablelibtmux/libtmux-go is public and reachablegithub.com/libtmux/libtmux-go ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/libtmux/libtmux-go ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model4 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmcp
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][libtmux-mcp-command] 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][guide-diagnose-startup]: 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][guide-connect-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][contract-which-tmux] has the precedence rules.
[-socket-name][guide-choose-a-server]: 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][workspace-cli-load] 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][guide-choose-a-server]: 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][split_window]: make room beside your pane
[split_window][split_window] adds a pane and returns its id. A new pane is
given time to start, so [run_shell_command][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_text]: wait for what a pane prints
[wait_for_text][wait_for_text] watches a pane and returns when a pattern
appears, or when a stop pattern appears first.
[capture_since][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][mcp-waitceilingenvironmentvariable].
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][contract-wait-ends] has the rest.
[run_shell_command][run_shell_command]: run a command and read its exit status
[run_shell_command][run_shell_command] waits for the command and returns its
exit status and output, without reading the screen at all.
[send_keys][send_keys] and [paste_text][paste_text] send input and return.
The trace runs a command that prints "bounded work" and gets back
"exit_status":0.
[run_shell_command][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][contract-bounded-reads] lists.
- One call can make several reads.
[
call_read_tools_batch][call_read_tools_batch] answers a list ofinspectcalls with one row each. - Checking is not capturing. The listing tools report what exists without
reading what any pane shows. [
snapshot_pane][snapshot_pane] returns a pane's metadata and content together.
The tools
The tools come in [toolsets][topic-tool-selection]. A toolset is a named group of tools, and it is what an operator grants or withholds:
inspectreads tmux and what panes show, and changes nothing.managerearranges what exists: it renames, resizes, selects, and moves.executecreates sessions, windows, and panes, and sends input to them.teardownkills sessions, windows, and panes, and clears scrollback.
TOOLS.md has every tool's arguments and what it returns, and the documentation site gives each tool the page linked above. That reference is for searching, which is why it is not here.
Four behaviours matter before you grant execute:
- Input goes where tmux sends it. With
synchronize-paneson, tmux types into every pane of the window. [send_keys][send_keys] reports the linked panes before it sends. - A new pane is given time to start. Input tools wait for its shell to
reach the prompt, so [
split_window][split_window] then [run_shell_command][run_shell_command] works. - Copy mode is left to the person. Reads never take over an attached
view, and [
get_pane_info][get_pane_info] reports when a pane is in a mode. - A pane someone is viewing is refused. The input tools do not type into a
pane a tmux client is showing, unless you launch the server with
[
LIBTMUX_ALLOW_ATTENDED_INPUT][mcp-allowattendedinputenvironmentvariable].
[The contract][contract-input] has the rest of each.
Limiting what a client can do
[LIBTMUX_TOOLSETS][mcp-toolsetsenvironmentvariable]: choose the toolsets
It takes toolset names separated by commas, in any order. Without it the
server grants inspect, manage, and execute.
teardownis never in that default. Ask for it by name.- A value that is set and empty grants no toolset, and there is no
nonekeyword.
To see the effect without a client, list what the server offers with one toolset:
$ LIBTMUX_TOOLSETS=inspect libtmux-mcp -tools
A client gets the same selection from the environment it starts the server with:
$ claude mcp add tmux \
-e LIBTMUX_TOOLSETS=inspect \
-- libtmux-mcp -socket-name default
[LIBTMUX_TOOLS][mcp-toolsenvironmentvariable] and [LIBTMUX_EXCLUDE_TOOLS][mcp-excludetoolsenvironmentvariable]: name exact tools
[LIBTMUX_TOOLS][mcp-toolsenvironmentvariable] adds tools by name to what the
toolsets grant, and
[LIBTMUX_EXCLUDE_TOOLS][mcp-excludetoolsenvironmentvariable] then removes
tools by name. Excluding a tool also removes it from what
[call_read_tools_batch][call_read_tools_batch] may call.
This lists the default tools without [send_keys][send_keys] and
[send_keys_batch][send_keys_batch]:
$ LIBTMUX_EXCLUDE_TOOLS=send_keys,send_keys_batch libtmux-mcp -tools
A name that matches no tool, or an empty item in either list, stops the server at startup, before it opens tmux.
Choosing tools shapes what a client is offered. Every call runs with your user's authority. [The contract][contract-exact-tools] covers the variables from earlier releases.
[LIBTMUX_ALLOW_ATTENDED_INPUT][mcp-allowattendedinputenvironmentvariable]: allow input to a pane someone is viewing
Every input tool refuses a pane that a tmux client is viewing, so an agent does
not type into the window a person is looking at. That refusal is the default.
To let the agent type into the window you are viewing, launch the server with
LIBTMUX_ALLOW_ATTENDED_INPUT=1:
$ claude mcp add tmux \
-e LIBTMUX_ALLOW_ATTENDED_INPUT=1 \
-- libtmux-mcp -socket-name default
The setting lifts that one refusal. A dead pane, a pane with input disabled, a
pane in a mode, and a synchronized pane that has such a member are still
refused. The only accepted value is 1. Any other value, including an empty
one, stops startup with a message that names the variable.
The server reads it once, at startup. tmux://capabilities reports it as
allowAttendedInput, and libtmux-mcp -doctor prints it.
[libtmux-mcp -tools][guide-inspect-the-selection]: see what a client would be offered
$ libtmux-mcp -tools
It prints the tools the server would advertise: each one's toolset, which processes it can reach, and a sentence on what it does. Below them it prints the prompts the same selection lists, each with the tools it names. Give it the flags and environment the client gives the server, because they decide the listing.
[tmux://capabilities][mcp-capabilitiesresourceuri]: what each tool says about itself
Each tool describes what it reaches and changes, under
_meta["com.git-pull.libtmux-mcp/capability"]. The resource
tmux://capabilities reports the same descriptions beside the selection in
force, and lists the resources that read the hierarchy.
[The contract][contract-capability-disclosure] lists them.
Settings
Flags choose the tmux server once, at startup:
| Flag | Meaning |
|---|---|
-socket-path |
an explicit socket path; when set, it wins over everything else |
-socket-name |
a tmux socket name; when set, it wins over both socket variables below |
-binary |
the tmux executable; empty uses [LIBTMUX_TMUX_BIN][mcp-binaryenvironmentvariable], then finds tmux on PATH |
Other flags answer a question and exit, which is what a config entry that will not start needs:
| Flag | Answers |
|---|---|
-version |
which build this is |
-tools |
the tools and toolsets a client would see |
-doctor |
which socket it reaches, what is on it, whether it is running inside that tmux itself, and whether input may reach a pane a client is viewing |
The environment sets the rest:
| Variable | Does |
|---|---|
[LIBTMUX_TOOLSETS][mcp-toolsetsenvironmentvariable] |
selects any unordered subset of the toolsets |
[LIBTMUX_TOOLS][mcp-toolsenvironmentvariable] |
includes exact tool names after toolset expansion |
[LIBTMUX_EXCLUDE_TOOLS][mcp-excludetoolsenvironmentvariable] |
removes exact names after every inclusion |
[LIBTMUX_ALLOW_ATTENDED_INPUT][mcp-allowattendedinputenvironmentvariable] |
1 lets the input tools type into a pane a tmux client is viewing; unset refuses it |
[LIBTMUX_SOCKET_PATH][mcp-socketpathenvironmentvariable] |
selects the socket path when no socket flag selects one; wins over [LIBTMUX_SOCKET][mcp-socketenvironmentvariable] |
[LIBTMUX_SOCKET][mcp-socketenvironmentvariable] |
names the tmux socket when no socket flag and no LIBTMUX_SOCKET_PATH select one |
[LIBTMUX_TMUX_CONFIG][mcp-tmuxconfigenvironmentvariable] |
selects a nonempty absolute tmux configuration path |
[LIBTMUX_TMUX_BIN][mcp-binaryenvironmentvariable] |
selects the tmux executable when -binary is empty |
[LIBTMUX_MCP_WAIT_MAX_SECONDS][mcp-waitceilingenvironmentvariable] |
the longest any one wait may run; 300 by default |
[LIBTMUX_AUDIT][mcp-auditenvironmentvariable] |
stderr, or a path, to record every call |
- A flag wins over its variable, and everything is fixed when the server starts. The names match the Python server's.
- The tmux executable is resolved once. A bad path fails at startup. A tmux server that is not running is fine, because tmux starts one on demand.
- A long wait is shortened. The reply says so in
effectiveTimeoutSecondsandtimeoutClamped.
[The contract][contract-settings] has the full text.
The pane it runs in
isCaller: knowing its own pane
Every pane the server reports carries isCaller: true for the pane it runs
in, false for any other, and null when the server is not in a pane at all.
[get_server_info][get_server_info] answers the same question directly.
The server reads TMUX_PANE and TMUX first. When they say nothing, it finds
the pane whose process is one of its own ancestors.
Asking before it types into your terminal
A write to the pane with isCaller true asks you first, through MCP's
elicitation request: a question the client puts to you on the server's behalf.
From protocol 2026-07-28 the question comes back in the result of the call, and
the client repeats the call with your answer.
- Declining fails the call, and a client that cannot ask is refused.
- A batch asks the same way, and declining stops the batch there. On protocol 2026-07-28 the batch asks all its questions before its first operation runs.
- With
synchronize-paneson, the question covers every pane the input would reach.
[The contract][contract-caller-pane] has the rest.
Known limits
- Some tools require a newer tmux. Startup and ordinary tools support
3.3a, including
capture_sinceandrun_shell_command. Non-emptypaste_textrequires 3.4 before staging any buffer;wait_for_textpolls withcapture-panebelow 3.7 and follows control output from 3.7. Restricted tools return an explicit version error on older supported daemons. The runtime uses subprocess commands below 3.7 and a retained control connection from 3.7. - Every tool is annotated as destructive. [
list_sessions][list_sessions] included, each carriesdestructiveHint=trueand noreadOnlyHint. Classify bytmuxEffectsin each tool's_meta. tools/listis large. More than half of it is the_metadescription. A client that wants a smaller reply can ignore_meta.- Some tools spell results differently.
[
run_shell_command][run_shell_command], [send_keys][send_keys], [paste_text][paste_text], and [clear_pane_scrollback][clear_pane_scrollback] return fields such asexit_status; the rest return fields such aspaneId. - An empty
TMUXcounts as set. Input tools refuse whenTMUXorTMUX_PANEis set to nothing. Unset them instead.
[The contract][contract-known-limits] gives the reason for each, and PARITY.md covers the result spellings.
tmux MCP questions
What tools does tmux MCP provide?
It exposes 4 tools, including inspect, manage, execute, teardown.
What are the requirements to run this server?
You need Go 1.26 or newer and tmux 3.3a or newer available on your PATH.
What happens to tmux sessions when the MCP client closes?
Closing the client ends the MCP process and its connections, but the tmux sessions themselves remain running.