libtmux MCP server
Commit 12 Nov 2026Memungkinkan AI agent untuk mengelola sesi, window, dan pane tmux dengan menjalankan command, membaca output terminal, serta mengorkestrasi lingkungan terminal.
Juga dikenal sebagai tmux-python/libtmux-mcp
- Stars
- 14
- Tools
- —
- Unduhan, 30 hari
- —
- Versi terbaru
- —
- Commit terakhir
- 12 Nov 2026
- Lisensi
- MIT
Apa itu libtmux MCP?
Memungkinkan AI agent untuk mengelola sesi, window, dan pane tmux dengan menjalankan command, membaca output terminal, serta mengorkestrasi lingkungan terminal.
Ringkasan dibuat dari README proyek
Tentang libtmux MCP server
libtmux-mcp memungkinkan Anda mengelola lingkungan terminal dan proses yang berjalan lama langsung dari dalam AI agent. Server ini menyediakan jembatan antara client Model Context Protocol dan tmux, yang memungkinkan agent untuk membuat sesi, mengelola window, dan mengontrol pane secara individu. Server ini dirancang bagi developer yang menggunakan tool seperti Claude Desktop, Claude Code, Codex CLI, atau Gemini CLI agar asisten AI mereka dapat berinteraksi langsung dengan lingkungan terminal.
Anda dapat menyiapkan server ini secara lokal menggunakan uvx atau dengan menambahkannya ke konfigurasi client Anda. Server ini menyertakan tool khusus untuk orkestrasi terminal yang canggih, seperti run_command untuk mengeksekusi shell command lengkap dengan exit status, wait_for_text untuk memantau output tanpa polling terus-menerus, dan capture_since untuk membaca baris terminal baru saja. Server ini juga menawarkan manajemen pane melalui tool seperti split_window, resize_pane, dan send_keys_batch untuk berinteraksi dengan user interface berbasis teks.
Implementasi ini berfokus pada efisiensi dan keamanan. Server ini menggunakan history suppression agar command dari agent tidak masuk ke shell history dan menyertakan pengaman untuk mencegah agent secara tidak sengaja mematikan sesi host miliknya sendiri. Developer dapat lebih menyempurnakan kapabilitas agent dengan menggunakan environment variable LIBTMUX_TOOLSETS untuk menyertakan atau mengecualikan grup tool tertentu seperti inspect, manage, execute, atau teardown.
Apa yang bisa Anda lakukan dengannya
- 1Eksekusi test otomatisMinta agent untuk memulai sesi tmux baru dan menjalankan test suite tertentu sambil memantau hasilnya.
Ditulis berdasarkan README proyek. Setiap use case diperiksa terhadap kutipan dari README tersebut.
Pengecekan otomatis
Berjalan 14 Nov 2026Laporan lengkap →Belum diverifikasi. Sebuah server memerlukan skor 80, tidak ada temuan serius, dan data yang cukup untuk kami periksa. Cara kerja checks · Yang perlu diperbaiki untuk menambah poin
- Source repository terhubung dan dapat dijangkautmux-python/libtmux-mcp is public and reachablegithub.com/tmux-python/libtmux-mcp ↗Lolos
- Nama paket mencantumkan repositori ini sebagai sumbernyaTidak diperiksa
- Provenance build (atestasi Sigstore)Tidak diperiksa
- Lisensi open source (OSI)MITspdx.org/licenses/MIT.html ↗Lolos
- Ada commit atau release dalam satu tahun terakhirLast commit or release 2026-11-12github.com/tmux-python/libtmux-mcp ↗Lolos
- OpenSSF ScorecardTidak diperiksa
- Nama package tidak mirip dengan package populerTidak diperiksa
- Tidak ada advisory kritis pada paket atau dependensinyaTidak diperiksa
- Tidak ada instruksi tersembunyi untuk model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersLolos
- Tools yang bersifat destruktif telah diberi labelTidak diperiksa
- Endpoint remote merespons handshake MCPTidak diperiksa
README
Lihat di GitHublibtmux-mcp
A Model Context Protocol server for tmux, built on libtmux.
[!WARNING] Alpha. Releases carry an
-alphaprerelease 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
| Module | Tools |
|---|---|
| Server | list_servers, list_sessions, create_session, kill_server, get_server_info |
| Batch | call_read_tools_batch |
| 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 | run_command, send_keys, send_keys_batch, paste_text, capture_pane, capture_since, snapshot_pane, search_panes, find_pane_by_position, get_pane_info, wait_for_text, wait_for_channel, signal_channel, 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 |
| Buffers | load_buffer, paste_buffer, show_buffer, delete_buffer |
| Hooks | show_hooks, show_hook |
Quickstart
Requirements: Python 3.11+, 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/ -xin it.Agent: Created session
apiwith windowtests. Running pytest now. Here's the output — 14 passed, 2 failed. The failures are intest_auth.py::test_token_refreshandtest_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
Attribution
Please use the following BibTeX template to cite libtmux-mcp in scientific discourse:
@misc{libtmux-mcp,
author = {Tony Narlock},
year = {2026},
note = {https://libtmux-mcp.git-pull.com},
title = {libtmux-mcp: MCP server for tmux}
}
License
MIT
Pertanyaan tentang libtmux MCP
Apakah server ini siap untuk penggunaan produksi?
Belum, server ini saat ini masih dalam tahap Alpha, yang berarti API belum stabil dan rilis dapat berubah atau menghapus identifier tanpa pemberitahuan.
Dapatkah agent menjalankan command tanpa mengotori shell history?
Ya, tool run_command menggunakan history suppression untuk memastikan input yang dihasilkan agent tidak masuk ke dalam shell history secara default.