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, 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.

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