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