libtmux-mcp

A Model Context Protocol server for tmux, built on libtmux.

[!WARNING] Alpha. Releases carry an -alpha prerelease tag. The API is not settled, and any release may change or remove exported identifiers without a deprecation period. Pin an exact version. Not recommended for production.

Give your AI agent hands inside the terminal — create sessions, run commands, read output, orchestrate panes.

Tools

Quickstart

Requirements: Python 3.10+, tmux >= 3.2a on $PATH.

The distribution is libtmux-mcp, the import is libtmux_mcp, and the installed executable is libtmux-mcp.

Install and run:

$ uvx libtmux-mcp

Claude Code

$ claude mcp add tmux -- uvx libtmux-mcp

Codex CLI

$ codex mcp add tmux -- uvx libtmux-mcp

Gemini CLI

$ gemini mcp add tmux uvx -- libtmux-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "tmux": {
      "command": "uvx",
      "args": ["libtmux-mcp"]
    }
  }
}

More clients and JSON config: client setup docs

What it feels like

You: Create a session called "api" and run pytest tests/api/ -x in it.

Agent: Created session api with window tests. Running pytest now. Here's the output — 14 passed, 2 failed. The failures are in test_auth.py::test_token_refresh and test_auth.py::test_expired_session. Want me to open those files?

The agent manages tmux directly. No copy-pasting terminal output. No switching windows to check on long-running processes.

When the server earns its keep

For a single tmux send-keys, the server doesn't. It earns its keep the moment the agent has to wait, inspect, or avoid damaging the terminal it is using — pytest finishing, a dev server printing its port, a deploy log settling. The difference then is not more access to tmux, but a better place to put the control loop.

The server-side moves are:

Running. run_command sends an authored shell command, waits for deterministic completion, and returns exit status plus tail-preserved output as one typed value. The command and its completion signal reach the shell as one space-prefixed event, so best-effort history suppression keeps agent-generated input out of shell history by default. The alternative — hand-rolled send-keys plus wait-for plus a pane capture — leaves every typed command, signal included, in shell history.

Driving. send_keys_batch sends several ordered raw-input operations for TUIs and persistent shell interaction. It is deliberately not a workflow DSL; command completion stays in run_command, and repeated observation stays in capture_since.

Waiting. wait_for_text blocks inside the server until a condition fires for output the agent does not author. The alternative is the model polling capture-pane in a loop, paying both context tokens and round-trip latency for every turn.

Reading. snapshot_pane returns content, cursor, copy-mode state, and scroll offset as one typed value. The alternative is several tmux invocations stitched together with regex.

Observing. capture_since returns a cursor with the current pane content, then returns only newly written or rewritten rows on follow-up calls. The alternative is re-sending the same scrollback to the model on every check.

Guarding. The server detects the agent's own pane across sockets and declines to end its own — kill_session on itself fails loudly instead of silently terminating the host environment the agent is running in. LIBTMUX_TOOLSETS (inspect, manage, execute, teardown) drops whole toolsets from the client's tool list before any prompt is built. The sets are unordered, so inspect,teardown is a legal surface. Dropping one is inventory and MCP tool-call configuration, not containment: an enabled execute tool can type the equivalent of anything it hides.

Documentation

Full docs, guides, and tool reference: libtmux-mcp.git-pull.com

Development

Clone and install:

$ git clone https://github.com/tmux-python/libtmux-mcp.git

$ cd libtmux-mcp

$ uv sync --all-extras --dev

Run the server locally:

$ uv run libtmux-mcp

Run tests:

$ uv run pytest

See CONTRIBUTING.md for the gates, and WRITING.md for how this project writes prose, docstrings, and MCP tool descriptions.

Related projects

• libtmux — Python API for tmux
• tmuxp — tmux session manager
• The Tao of tmux — the book

License

MIT