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

Module	Tools
Server	list_sessions, create_session, kill_server, get_server_info
Session	list_windows, get_session_info, create_window, rename_session, select_window, kill_session
Window	list_panes, get_window_info, split_window, rename_window, select_layout, resize_window, move_window, kill_window
Pane	send_keys, paste_text, capture_pane, capture_since, snapshot_pane, search_panes, get_pane_info, wait_for_text, wait_for_content_change, display_message, select_pane, swap_pane, resize_pane, set_pane_title, clear_pane, pipe_pane, enter_copy_mode, exit_copy_mode, respawn_pane, kill_pane
Options	show_option, set_option
Environment	show_environment, set_environment

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 three:

Waiting. wait_for_text and wait_for_content_change block inside the server until the condition fires. 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 (read, read+send, read+send+kill) 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