libtmux-mcp

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

[!WARNING] Pre-alpha. APIs may change. Contributions and feedback welcome.

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

Tools

Quickstart

Requirements: Python 3.10+, tmux on $PATH.

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 and wait_for_content_change block 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 self-destructive operations — kill_session on itself fails loudly instead of silently terminating the host environment the agent is running in. LIBTMUX_SAFETY (readonly, mutating, destructive) hides whole tiers from the client's tool list before any prompt is built.

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 --dev

Run the server locally:

uv run libtmux-mcp

Run tests:

uv run pytest

Related projects

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

License

MIT