# libtmux-mcp

> Terminal control for AI agents, built on libtmux and FastMCP.

## Get started

- [Quickstart](https://libtmux-mcp.git-pull.com/quickstart/): One happy path from zero to a working tool invocation.
- [Installation](https://libtmux-mcp.git-pull.com/installation/): Python 3.10+
- [MCP Clients](https://libtmux-mcp.git-pull.com/clients/): Pick your client, install method, and config scope below — the snippet updates accordingly. The scope row appears only for clients with more than one scope (Claude Desktop is always user-level so i...

## Use it

- [Tools](https://libtmux-mcp.git-pull.com/tools/): All tools accept an optional socket_name parameter for multi-server support. It defaults to the LIBTMUX_SOCKET env var. See configuration.
- [Prompts](https://libtmux-mcp.git-pull.com/prompts/): MCP prompts are reusable, parameterised text templates the server ships to its clients. A client renders a prompt by calling prompts/get; the rendered text is what the model sees. libtmux-mcp’s pro...
- [Resources](https://libtmux-mcp.git-pull.com/resources/): MCP resources are addressable documents the server exposes at tmux:// URIs. Clients read them via resources/read. All libtmux-mcp resources are resource templates — each URI includes a {?socket_nam...
- [Recipes](https://libtmux-mcp.git-pull.com/recipes/): Each recipe starts from a real workspace situation and traces the agent’s reasoning through discovery, decision, and action. The goal is not to show tool-call sequences – it is to show how an agent...
- [Configuration](https://libtmux-mcp.git-pull.com/configuration/): Runtime configuration for the libtmux-mcp server. For MCP client setup, see clients.

## Understand it

- [Topics](https://libtmux-mcp.git-pull.com/topics/): Explore libtmux-mcp’s core ideas and design at a high level.

## Reference

- [API Reference](https://libtmux-mcp.git-pull.com/reference/api/): MCP server entry point and lifecycle.
- [Compatibility](https://libtmux-mcp.git-pull.com/reference/compatibility/): Python
- [Glossary](https://libtmux-mcp.git-pull.com/glossary/): Model Context Protocol. A standard for AI agents to interact with tools and resources.

## Project

- [Project](https://libtmux-mcp.git-pull.com/project/): Information for contributors and maintainers.
- [Changelog](https://libtmux-mcp.git-pull.com/history/): Notes on upcoming releases will be added here
- [Migration notes](https://libtmux-mcp.git-pull.com/migration/): Migration and deprecation notes for libtmux-mcp are here, see history for the full release log.

## Documentation

- [Badge & Role Demo](https://libtmux-mcp.git-pull.com/demo/): A showcase of the custom Sphinx roles and visual elements available in libtmux-mcp documentation.
- [Code style](https://libtmux-mcp.git-pull.com/project/code-style/): libtmux-mcp uses ruff for linting and formatting:
- [Development](https://libtmux-mcp.git-pull.com/project/contributing/): Install git and uv (install)
- [Releasing](https://libtmux-mcp.git-pull.com/project/releasing/): libtmux-mcp follows PEP 440 with alpha suffixes during pre-1.0 development (e.g. 0.1.0a0).
- [Middleware](https://libtmux-mcp.git-pull.com/reference/api/middleware/): Middleware for libtmux MCP server.
- [Models](https://libtmux-mcp.git-pull.com/reference/api/models/): Pydantic models for MCP tool inputs and outputs.
- [Server](https://libtmux-mcp.git-pull.com/reference/api/server/): FastMCP server instance for libtmux.
- [Tools](https://libtmux-mcp.git-pull.com/reference/api/tools/): MCP tools for tmux server operations.
- [Utilities](https://libtmux-mcp.git-pull.com/reference/api/utils/): Shared utilities for libtmux MCP server.
- [Delete buffer](https://libtmux-mcp.git-pull.com/tools/buffer/delete-buffer/): Delete an MCP-owned buffer.
- [Buffer tools](https://libtmux-mcp.git-pull.com/tools/buffer/): tmux paste buffers are a server-global namespace shared by every client on the same socket. The buffer tools in libtmux-mcp expose a narrow, agent-namespaced subset: every allocation gets a UUID-sc...
- [Load buffer](https://libtmux-mcp.git-pull.com/tools/buffer/load-buffer/): Load text into a new agent-namespaced tmux paste buffer.
- [Paste buffer](https://libtmux-mcp.git-pull.com/tools/buffer/paste-buffer/): Paste an MCP-owned buffer into a pane.
- [Show buffer](https://libtmux-mcp.git-pull.com/tools/buffer/show-buffer/): Read back the contents of an MCP-owned buffer.
- [Hook tools](https://libtmux-mcp.git-pull.com/tools/hook/): tmux hooks let you attach commands to lifecycle events — pane-exited, session-renamed, command-error, and so on. libtmux-mcp exposes read-only hook introspection so agents can audit what hooks the ...
- [Show hook](https://libtmux-mcp.git-pull.com/tools/hook/show-hook/): Look up a specific tmux hook by name.
- [Show hooks](https://libtmux-mcp.git-pull.com/tools/hook/show-hooks/): List configured tmux hooks at the given scope.
- [Capture pane](https://libtmux-mcp.git-pull.com/tools/pane/capture-pane/): Capture the visible contents of a tmux pane (terminal scrollback).
- [Capture since](https://libtmux-mcp.git-pull.com/tools/pane/capture-since/): Capture new tmux terminal scrollback since the previous cursor.
- [Clear pane](https://libtmux-mcp.git-pull.com/tools/pane/clear-pane/): Clear the contents of a tmux pane.
- [Evaluate tmux format string (display_message)](https://libtmux-mcp.git-pull.com/tools/pane/display-message/): Evaluate a tmux format string against a target and return the expanded value.
- [Enter copy mode](https://libtmux-mcp.git-pull.com/tools/pane/enter-copy-mode/): Enter copy mode in a tmux pane, optionally scrolling up.
- [Exit copy mode](https://libtmux-mcp.git-pull.com/tools/pane/exit-copy-mode/): Exit copy mode in a tmux pane.
- [Find pane by position](https://libtmux-mcp.git-pull.com/tools/pane/find-pane-by-position/): Find the pane occupying a corner of a tmux window.
- [Get pane info](https://libtmux-mcp.git-pull.com/tools/pane/get-pane-info/): Get detailed information about a tmux pane.
- [Pane tools](https://libtmux-mcp.git-pull.com/tools/pane/): Pane-scoped tools — read and drive individual terminals, wait for output, copy mode, and channel sync.
- [Kill pane](https://libtmux-mcp.git-pull.com/tools/pane/kill-pane/): Kill (close) a tmux pane. Requires exact pane_id (e.g. ‘%5’).
- [Paste text](https://libtmux-mcp.git-pull.com/tools/pane/paste-text/): Paste multi-line text into a pane using tmux paste buffers.
- [Pipe pane](https://libtmux-mcp.git-pull.com/tools/pane/pipe-pane/): Log a pane’s live output to a file (or stop an active log).
- [Resize pane](https://libtmux-mcp.git-pull.com/tools/pane/resize-pane/): Resize a tmux pane.
- [Respawn pane](https://libtmux-mcp.git-pull.com/tools/pane/respawn-pane/): Restart a pane’s process in place, preserving pane_id and layout.
- [Search panes](https://libtmux-mcp.git-pull.com/tools/pane/search-panes/): Search visible terminal text across all tmux panes.
- [Select pane](https://libtmux-mcp.git-pull.com/tools/pane/select-pane/): Select (focus) a tmux pane by ID or direction.
- [Send keys](https://libtmux-mcp.git-pull.com/tools/pane/send-keys/): Send keys (commands or text) to a tmux pane.
- [Set pane title](https://libtmux-mcp.git-pull.com/tools/pane/set-pane-title/): Set the title of a tmux pane.
- [Signal channel](https://libtmux-mcp.git-pull.com/tools/pane/signal-channel/): Signal a tmux wait-for channel, waking any blocked waiters.
- [Snapshot pane](https://libtmux-mcp.git-pull.com/tools/pane/snapshot-pane/): Snapshot a tmux pane: visible terminal output, cursor, mode, scroll.
- [Swap pane](https://libtmux-mcp.git-pull.com/tools/pane/swap-pane/): Swap the positions of two panes.
- [Wait for channel](https://libtmux-mcp.git-pull.com/tools/pane/wait-for-channel/): tmux’s wait-for command exposes named, server-global channels that clients can signal and block on. These give agents an explicit synchronization primitive — strictly cheaper in agent turns than po...
- [Wait for content change](https://libtmux-mcp.git-pull.com/tools/pane/wait-for-content-change/): Wait for any content change in a tmux pane.
- [Wait for text](https://libtmux-mcp.git-pull.com/tools/pane/wait-for-text/): Wait for NEW text to appear in a tmux pane.
- [Create session](https://libtmux-mcp.git-pull.com/tools/server/create-session/): Create a new tmux session.
- [Get server info](https://libtmux-mcp.git-pull.com/tools/server/get-server-info/): Get information about the tmux server.
- [Server tools](https://libtmux-mcp.git-pull.com/tools/server/): Server & process-level tools — discover sessions, control the tmux daemon, read/write server-scoped state.
- [Kill server](https://libtmux-mcp.git-pull.com/tools/server/kill-server/): Kill the tmux server and all its sessions.
- [List servers](https://libtmux-mcp.git-pull.com/tools/server/list-servers/): Discover live tmux servers under the current user’s $TMUX_TMPDIR.
- [List sessions](https://libtmux-mcp.git-pull.com/tools/server/list-sessions/): List tmux sessions (terminal workspaces) on a tmux server.
- [Set environment](https://libtmux-mcp.git-pull.com/tools/server/set-environment/): Set a tmux environment variable.
- [Set option](https://libtmux-mcp.git-pull.com/tools/server/set-option/): Set a tmux option value.
- [Show environment](https://libtmux-mcp.git-pull.com/tools/server/show-environment/): Show tmux environment variables.
- [Show option](https://libtmux-mcp.git-pull.com/tools/server/show-option/): Show a tmux option value.
- [Create window](https://libtmux-mcp.git-pull.com/tools/session/create-window/): Create a new window in a tmux session.
- [Get session info](https://libtmux-mcp.git-pull.com/tools/session/get-session-info/): Return metadata for a single tmux session (ID, name, window count, activity).
- [Session tools](https://libtmux-mcp.git-pull.com/tools/session/): Session-scoped tools — enumerate windows, rename or kill a session, switch windows within it.
- [Kill session](https://libtmux-mcp.git-pull.com/tools/session/kill-session/): Kill a tmux session.
- [List windows](https://libtmux-mcp.git-pull.com/tools/session/list-windows/): List tmux windows (terminal tabs) in a session, or across the server.
- [Rename session](https://libtmux-mcp.git-pull.com/tools/session/rename-session/): Rename a tmux session.
- [Select window](https://libtmux-mcp.git-pull.com/tools/session/select-window/): Select (focus) a tmux window by ID, index, or direction.
- [Get window info](https://libtmux-mcp.git-pull.com/tools/window/get-window-info/): Return metadata for a single tmux window (ID, name, layout, dimensions).
- [Window tools](https://libtmux-mcp.git-pull.com/tools/window/): Window-scoped tools — enumerate panes, split / rename / relayout / resize / move / kill windows.
- [Kill window](https://libtmux-mcp.git-pull.com/tools/window/kill-window/): Kill (close) a tmux window. Requires exact window_id (e.g. ‘@3’).
- [List panes](https://libtmux-mcp.git-pull.com/tools/window/list-panes/): List tmux panes (terminal multiplexer splits) in a window, session, or server.
- [Move window](https://libtmux-mcp.git-pull.com/tools/window/move-window/): Move a window to a different index or session.
- [Rename window](https://libtmux-mcp.git-pull.com/tools/window/rename-window/): Rename a tmux window.
- [Resize window](https://libtmux-mcp.git-pull.com/tools/window/resize-window/): Resize a tmux window.
- [Select layout](https://libtmux-mcp.git-pull.com/tools/window/select-layout/): Set the layout of a tmux window.
- [Split window](https://libtmux-mcp.git-pull.com/tools/window/split-window/): Split a tmux window to create a new pane.
- [Architecture](https://libtmux-mcp.git-pull.com/topics/architecture/): For contributors who need to understand the codebase internals.
- [Completion](https://libtmux-mcp.git-pull.com/topics/completion/): libtmux-mcp inherits FastMCP’s built-in MCP completion behaviour. We don’t hand-author completion providers — the argument shapes on our prompts and resource templates are what the client sees.
- [Concepts](https://libtmux-mcp.git-pull.com/topics/concepts/): The mental model you need to use libtmux-mcp effectively.
- [Gotchas](https://libtmux-mcp.git-pull.com/topics/gotchas/): Things that will bite you if you don’t know about them in advance. For symptom-based debugging, see troubleshooting.
- [Logging](https://libtmux-mcp.git-pull.com/topics/logging/): libtmux-mcp uses Python’s standard logging module under the libtmux_mcp.* namespace. FastMCP forwards server-side log records to connected MCP clients via the MCP logging capability. No manual wiri...
- [Pagination](https://libtmux-mcp.git-pull.com/topics/pagination/): libtmux-mcp follows the MCP pagination spec: tools/list, prompts/list, resources/list, and resources/templates/list all return an opaque nextCursor when a page is truncated, and accept cursor on th...
- [Agent prompting guide](https://libtmux-mcp.git-pull.com/topics/prompting/): How to write effective instructions for AI agents using libtmux-mcp.
- [Safety tiers](https://libtmux-mcp.git-pull.com/topics/safety/): libtmux-mcp uses a three-tier safety system to control which tools are available to AI agents.
- [Troubleshooting](https://libtmux-mcp.git-pull.com/topics/troubleshooting/): Symptom-based guide. Find your problem, follow the steps.