libtmux-mcp 0.1.0a22 · Source
For MCP client requests, use the tool reference. This page covers language APIs for embedding or extending the server.
The Python API and MCP protocol expose different interfaces. Python callers import functions and models; MCP clients send registered tool names and schema-validated arguments.
MCP operationsLink to section
Browse the tool reference for the protocol catalog.
tools/list on a running server is the effective selection after
startup filtering. Registration defaults can differ from direct Python
function defaults, including command-history suppression.
The server also registers hierarchy resources and workflow prompts. These remain available independently of the toolset selection.
Python entry pointsLink to section
libtmux_mcp.server.build_mcp_server() returns the registered production
FastMCP server. run_server() serves it over stdio. The factory uses the
module’s server instance; repeated calls do not create independent
configuration contexts.
The package separates tool functions, typed models, middleware, resource handlers, and prompt recipes. Model classes describe request/result data; their existence does not make them separate MCP tools.
Use Examples to inspect the protocol with an in-process client. Use the Workspace builder API for tmuxp configuration and builders.
API declarations
Follow a declaration for its signature, members, documentation, and source.
Exports
libtmux_mcp.middleware.AuditMiddleware- Emit a structured log record per tool invocation.
libtmux_mcp.models.BufferContent- Structured result of show_buffer.
libtmux_mcp.models.BufferRef- Handle returned by load_buffer.
libtmux_mcp.prompts.recipes.build_dev_workspace- Construct a simple 3-pane development session.
libtmux_mcp.server.build_mcp_server- Build and return the registered production FastMCP server.
libtmux_mcp.tools.batch_tools.call_read_tools_batch- Call several inspect tools serially and return per-tool results.
libtmux_mcp.tools.pane_tools.io.CAPTURE_DEFAULT_MAX_LINESlibtmux_mcp.tools.pane_tools.capture_pane- Capture the visible contents of a tmux pane (terminal scrollback).
libtmux_mcp.tools.pane_tools.capture_since- Capture new tmux terminal scrollback since the previous cursor.
libtmux_mcp.tools.pane_tools.capture_since.CAPTURE_SINCE_DEFAULT_MAX_BYTESlibtmux_mcp.tools.pane_tools.capture_since.CAPTURE_SINCE_DEFAULT_MAX_LINESlibtmux_mcp.models.CaptureSinceResult- Incremental pane capture result with an opaque resume cursor.
libtmux_mcp.tools.pane_tools.clear_pane- Clear the contents of a tmux pane.
libtmux_mcp.tools.server_tools.create_session- Create a new tmux session.
libtmux_mcp.tools.session_tools.create_window- Create a new window in a tmux session.
libtmux_mcp.middleware.DEFAULT_RESPONSE_LIMIT_BYTESlibtmux_mcp.server.DEFAULT_TOOLSETSlibtmux_mcp.tools.buffer_tools.delete_buffer- Delete an MCP-owned buffer.
libtmux_mcp.prompts.recipes.diagnose_failing_pane- Gather pane context and propose a root-cause hypothesis.
libtmux_mcp.tools.pane_tools.display_message- Read tmux variables against a target and return the substituted text.
libtmux_mcp.tools.pane_tools.enter_copy_mode- Enter copy mode in a tmux pane, optionally scrolling up.
libtmux_mcp.prompts.ENV_PROMPTS_AS_TOOLSlibtmux_mcp.models.EnvironmentResult- Result of a show_environment call.
libtmux_mcp.models.EnvironmentSetResult- Result of a set_environment call.
libtmux_mcp.tools.pane_tools.exit_copy_mode- Exit copy mode in a tmux pane.
libtmux_mcp.tools.pane_tools.find_pane_by_position- Find the pane occupying a corner of a tmux window.
libtmux_mcp.tools.pane_tools.get_pane_info- Get detailed information about a tmux pane.
libtmux_mcp.tools.server_tools.get_server_info- Get information about the tmux server.
libtmux_mcp.tools.session_tools.get_session_info- Return metadata for a single tmux session (ID, name, window count, activity).
libtmux_mcp.tools.window_tools.get_window_info- Return metadata for a single tmux window (ID, name, layout, dimensions).
libtmux_mcp.tools.pane_tools.state.HISTORY_LIMIT_FORMATlibtmux_mcp.models.HookEntry- One entry in a tmux hook array.
libtmux_mcp.models.HookListResult- Structured result for hook introspection.
libtmux_mcp.middleware.install_fastmcp_validation_log_filter- Install the FastMCP validation log redaction filter once.
libtmux_mcp.prompts.recipes.interrupt_gracefully- Interrupt a running command and verify the prompt returned.
libtmux_mcp.tools.pane_tools.kill_pane- Kill (close) a tmux pane. Requires exact pane_id (e.g. '%5').
libtmux_mcp.tools.server_tools.kill_server- Kill the tmux server and all its sessions.
libtmux_mcp.tools.session_tools.kill_session- Kill a tmux session.
libtmux_mcp.tools.window_tools.kill_window- Kill (close) a tmux window. Requires exact window_id (e.g. '@3').
libtmux_mcp.tools.window_tools.list_panes- List tmux panes (terminal multiplexer splits) in a window, session, or server.
libtmux_mcp.tools.server_tools.list_servers- Discover live tmux servers under the current user's $TMUX_TMPDIR.
libtmux_mcp.tools.server_tools.list_sessions- List tmux sessions (terminal workspaces) on a tmux server.
libtmux_mcp.tools.session_tools.list_windows- List tmux windows (terminal tabs) in a session, or across the server.
libtmux_mcp.tools.buffer_tools.load_buffer- Load text into a new agent-namespaced tmux paste buffer.
libtmux_mcp.main- Entry point for the libtmux MCP server.
libtmux_mcp.tools.batch_tools.MAX_BATCH_OPERATIONSlibtmux_mcp.server.mcplibtmux_mcp.tools.window_tools.move_window- Move a window to a different index or session.
libtmux_mcp.models.OptionResult- Result of a show_option call.
libtmux_mcp.models.OptionSetResult- Result of a set_option call.
libtmux_mcp.tools.pane_tools.state.PANE_STATE_FORMATlibtmux_mcp.models.PaneContentMatch- A pane whose captured content matched a search pattern.
libtmux_mcp.tools.pane_tools.lifecycle.PaneCornerlibtmux_mcp.models.PaneInfo- Serialized tmux pane.
libtmux_mcp.models.PaneSnapshot- Rich screen capture with metadata: content, cursor, mode, and scroll state.
libtmux_mcp.tools.buffer_tools.paste_buffer- Paste an MCP-owned buffer into a pane.
libtmux_mcp.tools.pane_tools.paste_text- Paste multi-line text into a pane using tmux paste buffers.
libtmux_mcp.tools.pane_tools.pipe_pane- Log a pane's live output to a file (or stop an active log).
libtmux_mcp.resources.hierarchy.register- Register hierarchy resources with the FastMCP instance.
libtmux_mcp.tools.batch_tools.register- Register generic MCP batch tools.
libtmux_mcp.tools.buffer_tools.register- Register buffer tools with the MCP instance.
libtmux_mcp.tools.env_tools.register- Register environment tools with the MCP instance.
libtmux_mcp.tools.hook_tools.register- Register hook inspection tools with the MCP instance.
libtmux_mcp.tools.option_tools.register- Register option tools with the MCP instance.
libtmux_mcp.tools.pane_tools.register- Register pane-level tools with the MCP instance.
libtmux_mcp.tools.server_tools.register- Register server-level tools with the MCP instance.
libtmux_mcp.tools.session_tools.register- Register session-level tools with the MCP instance.
libtmux_mcp.tools.wait_for_tools.register- Register wait-for channel tools with the MCP instance.
libtmux_mcp.tools.window_tools.register- Register window-level tools with the MCP instance.
libtmux_mcp.resources.hierarchy.register_completions- Answer argument completion for the tmux:// templates.
libtmux_mcp.prompts.register_prompts- Register the narrow prompt set with the MCP instance.
libtmux_mcp.resources.register_resources- Register all resource modules with the FastMCP instance.
libtmux_mcp.tools.register_tools- Register all tool modules with the FastMCP instance.
libtmux_mcp.tools.session_tools.rename_session- Rename a tmux session.
libtmux_mcp.tools.window_tools.rename_window- Rename a tmux window.
libtmux_mcp.tools.pane_tools.resize_pane- Resize a tmux pane.
libtmux_mcp.tools.window_tools.resize_window- Resize a tmux window.
libtmux_mcp.tools.pane_tools.respawn_pane- Restart a pane's process in place, preserving pane_id and layout.
libtmux_mcp.prompts.recipes.run_and_wait- Run a shell command in a tmux pane and wait for completion.
libtmux_mcp.tools.pane_tools.run_command- Run a shell command in a pane, wait for completion, and capture output.
libtmux_mcp.server.run_server- Run the MCP server.
libtmux_mcp.models.RunCommandResult- Result of running a shell command in a pane.
libtmux_mcp.tools.pane_tools.search.SEARCH_DEFAULT_LIMITlibtmux_mcp.tools.pane_tools.search.SEARCH_DEFAULT_MAX_LINES_PER_PANElibtmux_mcp.tools.pane_tools.search.SEARCH_MATCH_MAX_SECONDSlibtmux_mcp.tools.pane_tools.search.SEARCH_MAX_PATTERN_LENGTHlibtmux_mcp.tools.pane_tools.search_panes- Search visible terminal text across all tmux panes.
libtmux_mcp.models.SearchPanesResult- Paginated result of search_panes.
libtmux_mcp.tools.window_tools.select_layout- Set the layout of a tmux window.
libtmux_mcp.tools.pane_tools.select_pane- Select (focus) a tmux pane by ID or direction.
libtmux_mcp.tools.session_tools.select_window- Select (focus) a tmux window by ID, index, or direction.
libtmux_mcp.tools.pane_tools.send_keys- Send keys (commands or text) to a tmux pane.
libtmux_mcp.tools.pane_tools.send_keys_batch- Send an ordered batch of raw key/text operations to tmux panes.
libtmux_mcp.models.SendKeysBatchResult- Structured result for a batch of raw-input send operations.
libtmux_mcp.models.SendKeysOperation- One raw-input operation for batch sending.
libtmux_mcp.models.SendKeysOperationResult- Per-operation result from batch sending.
libtmux_mcp.models.ServerInfo- Serialized tmux server info.
libtmux_mcp.models.SessionInfo- Serialized tmux session.
libtmux_mcp.tools.env_tools.set_environment- Set a tmux environment variable.
libtmux_mcp.tools.option_tools.set_option- Set a tmux option value.
libtmux_mcp.tools.pane_tools.set_pane_title- Set the title of a tmux pane.
libtmux_mcp.tools.buffer_tools.show_buffer- Read back the contents of an MCP-owned buffer.
libtmux_mcp.tools.buffer_tools.SHOW_BUFFER_DEFAULT_MAX_LINESlibtmux_mcp.tools.env_tools.show_environment- Show tmux environment variables.
libtmux_mcp.tools.hook_tools.show_hook- Look up a specific tmux hook by name.
libtmux_mcp.tools.hook_tools.show_hooks- List configured tmux hooks at the given scope.
libtmux_mcp.tools.option_tools.show_option- Show a tmux option value.
libtmux_mcp.tools.wait_for_tools.signal_channel- Signal a tmux wait-for channel, waking blocked waiters.
libtmux_mcp.tools.pane_tools.snapshot_pane- Snapshot a tmux pane: visible terminal output, cursor, mode, scroll.
libtmux_mcp.tools.server_tools.SOCKET_NAME_EXEMPTlibtmux_mcp.tools.window_tools.split_window- Split a tmux window to create a new pane.
libtmux_mcp.tools.pane_tools.swap_pane- Swap the positions of two panes.
libtmux_mcp.middleware.TailPreservingResponseLimitingMiddleware- Response-limiter that keeps the tail of oversized output.
libtmux_mcp.models.ToolCallBatchResult- Structured result for a serial batch of MCP tool calls.
libtmux_mcp.models.ToolCallOperation- One nested MCP tool call for a batch wrapper.
libtmux_mcp.models.ToolCallOperationResult- Per-operation result from a generic MCP tool batch.
libtmux_mcp.middleware.ToolErrorResultMiddleware- Convert tool-call failures into rich ToolResult errors.
libtmux_mcp.middleware.ToolsetMiddleware- Filter tools to the enabled toolsets.
libtmux_mcp.tools.wait_for_tools.wait_for_channel- Block until a tmux wait-for channel is signalled.
libtmux_mcp.tools.pane_tools.wait_for_text- Wait for NEW output in a tmux pane, then return.
libtmux_mcp.models.WaitForTextResult- Result of a bounded wait for new pane output.
libtmux_mcp.models.WindowInfo- Serialized tmux window.