Tools¶

Batch tools¶

Generic MCP tool batching helpers.

libtmux_mcp.tools.batch_tools._content_block_to_dict(block)

¶

function[source]

function[source]

libtmux_mcp.tools.batch_tools._content_block_to_dict(block)

¶

Return a JSON-ready representation of an MCP content block.

Parameters:

block (Any)

Return type:

dict[str, Any]

libtmux_mcp.tools.batch_tools._result_error_text(result)

¶

function[source]

function[source]

libtmux_mcp.tools.batch_tools._result_error_text(result)

¶

Extract a readable error string from a FastMCP ToolResult.

Parameters:

result (ToolResult)

Return type:

str | None

libtmux_mcp.tools.batch_tools._tool_tier(tool_name, tags)

¶

function[source]

function[source]

libtmux_mcp.tools.batch_tools._tool_tier(tool_name, tags)

¶

Return the highest recognized safety tier for a registered tool.

Parameters:

• tool_name (str)

• tags (set[str])

Return type:

str

libtmux_mcp.tools.batch_tools._check_operation_allowed(*, tool_name, tool_tier, max_tier)

¶

function[source]

function[source]

libtmux_mcp.tools.batch_tools._check_operation_allowed(*, tool_name, tool_tier, max_tier)

¶

Raise when a nested tool exceeds this batch wrapper’s tier.

Parameters:

• tool_name (str)

• tool_tier (str)

• max_tier (str)

Return type:

None

async libtmux_mcp.tools.batch_tools._get_allowed_tool_tier(*, fastmcp, operation, max_tier)

¶

async function[source]

async function[source]

async libtmux_mcp.tools.batch_tools._get_allowed_tool_tier(*, fastmcp, operation, max_tier)

¶

Validate that one nested operation targets an allowed tool.

Parameters:

• fastmcp (FastMCP)

• operation (ToolCallOperation)

• max_tier (str)

Return type:

None

libtmux_mcp.tools.batch_tools._ensure_tool_result(tool_name, result)

¶

function[source]

function[source]

libtmux_mcp.tools.batch_tools._ensure_tool_result(tool_name, result)

¶

Return result as a ToolResult or raise a row-level error.

Parameters:

• tool_name (str)

• result (Any)

Return type:

ToolResult

libtmux_mcp.tools.batch_tools._batch_response_size(result)

¶

function[source]

function[source]

libtmux_mcp.tools.batch_tools._batch_response_size(result)

¶

Return the serialized byte size of FastMCP’s batch response envelope.

Parameters:

result (ToolCallBatchResult)

Return type:

int

libtmux_mcp.tools.batch_tools._operation_has_nested_payload(result)

¶

function[source]

function[source]

libtmux_mcp.tools.batch_tools._operation_has_nested_payload(result)

¶

Return True when a row still carries payload fields that can be elided.

Parameters:

result (ToolCallOperationResult)

Return type:

bool

libtmux_mcp.tools.batch_tools._limit_batch_result(result, *, max_bytes=DEFAULT_RESPONSE_LIMIT_BYTES)

¶

function[source]

function[source]

libtmux_mcp.tools.batch_tools._limit_batch_result(result, *, max_bytes=DEFAULT_RESPONSE_LIMIT_BYTES)

¶

Elide nested result payloads until the batch envelope fits.

Parameters:

• result (ToolCallBatchResult)

• max_bytes (int)

Return type:

ToolCallBatchResult

async libtmux_mcp.tools.batch_tools._call_one_tool(*, fastmcp, operation, index, max_tier)

¶

async function[source]

async function[source]

async libtmux_mcp.tools.batch_tools._call_one_tool(*, fastmcp, operation, index, max_tier)

¶

Call one nested tool and convert its outcome to a batch result row.

Parameters:

• fastmcp (FastMCP)

• operation (ToolCallOperation)

• index (int)

• max_tier (str)

Return type:

ToolCallOperationResult

async libtmux_mcp.tools.batch_tools._call_tools_batch(*, operations, on_error, max_tier, ctx)

¶

async function[source]

async function[source]

async libtmux_mcp.tools.batch_tools._call_tools_batch(*, operations, on_error, max_tier, ctx)

¶

Execute nested MCP tool calls serially through FastMCP.

Parameters:

• operations (list[ToolCallOperation])

• on_error (_OnError)

• max_tier (str)

• ctx (Context | None)

Return type:

ToolCallBatchResult

async libtmux_mcp.tools.batch_tools.call_readonly_tools_batch(operations, on_error='stop', ctx=None)

¶

async function[source]

async function[source]

async libtmux_mcp.tools.batch_tools.call_readonly_tools_batch(operations, on_error='stop', ctx=None)

¶

Call readonly MCP tools serially and return per-tool results.

Use when several read-only observations should be made in one agent turn. Each nested call still goes through FastMCP validation, middleware, and safety checks. Mutating and destructive tools are rejected even if the server process itself is running at a higher safety tier.

Parameters:

• operations (list[ToolCallOperation])

• on_error (_OnError)

• ctx (Context | None)

Return type:

ToolCallBatchResult

async libtmux_mcp.tools.batch_tools.call_mutating_tools_batch(operations, on_error='stop', ctx=None)

¶

async function[source]

async function[source]

async libtmux_mcp.tools.batch_tools.call_mutating_tools_batch(operations, on_error='stop', ctx=None)

¶

Call readonly or mutating MCP tools serially and return per-tool results.

Use for ordered tmux workflows where every step is still an existing typed MCP tool. Destructive tools are rejected regardless of the process-wide safety tier.

Parameters:

• operations (list[ToolCallOperation])

• on_error (_OnError)

• ctx (Context | None)

Return type:

ToolCallBatchResult

async libtmux_mcp.tools.batch_tools.call_destructive_tools_batch(operations, on_error='stop', ctx=None)

¶

async function[source]

async function[source]

async libtmux_mcp.tools.batch_tools.call_destructive_tools_batch(operations, on_error='stop', ctx=None)

¶

Call readonly, mutating, or destructive MCP tools serially.

This wrapper preserves the normal per-tool schemas and middleware but its tier permits destructive nested operations. Prefer the narrower readonly or mutating wrappers whenever possible.

Parameters:

• operations (list[ToolCallOperation])

• on_error (_OnError)

• ctx (Context | None)

Return type:

ToolCallBatchResult

libtmux_mcp.tools.batch_tools.register(mcp)

¶

function[source]

function[source]

libtmux_mcp.tools.batch_tools.register(mcp)

¶

Register generic MCP batch tools.

Parameters:

mcp (FastMCP)

Return type:

None

Server tools¶

MCP tools for tmux server operations.

libtmux_mcp.tools.server_tools.list_sessions(socket_name=None, filters=None)

¶

function[source]

function[source]

libtmux_mcp.tools.server_tools.list_sessions(socket_name=None, filters=None)

¶

List tmux sessions (terminal workspaces) on a tmux server.

Use for tmux multiplexer sessions — ‘this session’, ‘my workspace’, ‘the dev session’ — not login sessions or HTTP sessions. The starting point for discovery — call this before targeting specific sessions, windows, or panes.

Parameters:

• socket_name (str, optional) – tmux socket name. Defaults to LIBTMUX_SOCKET env var.

• filters (dict or str, optional) – Django-style filters as a dict (e.g. {"session_name__contains": "dev"}) or as a JSON string. Some MCP clients require the string form.

Returns:

List of session objects.

Return type:

list[SessionInfo]

libtmux_mcp.tools.server_tools.create_session(session_name=None, window_name=None, start_directory=None, x=None, y=None, environment=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.server_tools.create_session(session_name=None, window_name=None, start_directory=None, x=None, y=None, environment=None, socket_name=None)

¶

Create a new tmux session.

Check list_sessions first to avoid name conflicts. A new session starts with one window and one pane.

Parameters:

• session_name (str, optional) – Name for the new session.

• window_name (str, optional) – Name for the initial window.

• start_directory (str, optional) – Working directory for the session.

• x (int, optional) – Width of the initial window.

• y (int, optional) – Height of the initial window.

• environment (dict or str, optional) – Environment variables to set. Accepts either a dict of env vars or a JSON-serialized string of the same — the latter is the cursor-composer-1 workaround described in libtmux_mcp._utils._coerce_dict_arg().

• socket_name (str, optional) – tmux socket name. Defaults to LIBTMUX_SOCKET env var.

Returns:

The created session.

Return type:

SessionInfo

libtmux_mcp.tools.server_tools.kill_server(socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.server_tools.kill_server(socket_name=None)

¶

Kill the tmux server and all its sessions.

Destroys ALL sessions, windows, and panes on this server. Use kill_session to remove a single session instead. Self-kill protection prevents killing the server running this MCP process.

Parameters:

socket_name (str, optional) – tmux socket name. Defaults to LIBTMUX_SOCKET env var.

Returns:

Confirmation message.

Return type:

str

libtmux_mcp.tools.server_tools.get_server_info(socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.server_tools.get_server_info(socket_name=None)

¶

Get information about the tmux server.

Use to verify the tmux server is running before other operations. For session-level details, use list_sessions instead.

Parameters:

socket_name (str, optional) – tmux socket name. Defaults to LIBTMUX_SOCKET env var.

Returns:

Server information.

Return type:

ServerInfo

libtmux_mcp.tools.server_tools._is_tmux_socket_live(path)

¶

function[source]

function[source]

libtmux_mcp.tools.server_tools._is_tmux_socket_live(path)

¶

Return True if a tmux socket has a listener accepting connections.

Uses a UNIX-domain connect() with a short timeout rather than shelling out to tmux. $TMUX_TMPDIR/tmux-$UID/ routinely accumulates thousands of stale socket inodes from past servers — probing each one with tmux -L <name> ls would make list_servers() O(sockets * tmux-spawn-cost), easily tens of seconds on well-aged machines. Socket connect is kernel-fast (sub millisecond) and returns ECONNREFUSED immediately for dead inodes.

Parameters:

path (Path)

Return type:

bool

libtmux_mcp.tools.server_tools._probe_server_by_path(socket_path)

¶

function[source]

function[source]

libtmux_mcp.tools.server_tools._probe_server_by_path(socket_path)

¶

Return a ServerInfo for a live socket at socket_path.

Mirrors get_server_info()’s serialization but keys the Server by socket_path (-S) rather than socket name (-L) so callers can probe arbitrary tmux -S /path/... daemons that live outside $TMUX_TMPDIR. Returns None when the path is not a socket, has no listener, or the server cannot be queried. Probe failures are logged at debug level so operators can surface “why isn’t my custom socket appearing?” via verbose logging.

Parameters:

socket_path (Path)

Return type:

ServerInfo | None

libtmux_mcp.tools.server_tools.SOCKET_NAME_EXEMPT: frozenset[str] = frozenset({'call_destructive_tools_batch', 'call_mutating_tools_batch', 'call_readonly_tools_batch', 'list_servers'})

¶

data

data

libtmux_mcp.tools.server_tools.SOCKET_NAME_EXEMPT: frozenset[str] = frozenset({'call_destructive_tools_batch', 'call_mutating_tools_batch', 'call_readonly_tools_batch', 'list_servers'})

¶

Tools that intentionally do NOT accept socket_name because they either discover sockets themselves or coordinate nested tools whose arguments carry their own targeting. Read by test_registered_tools_accept_socket_name to enforce the agent-facing contract advertised in libtmux_mcp.server._BASE_INSTRUCTIONS. When you add a new discovery-style tool, append it here AND update the prose in _BASE_INSTRUCTIONS so the two stay in lockstep.

libtmux_mcp.tools.server_tools.list_servers(extra_socket_paths=None)

¶

function[source]

function[source]

libtmux_mcp.tools.server_tools.list_servers(extra_socket_paths=None)

¶

Discover live tmux servers under the current user’s $TMUX_TMPDIR.

Scans ${TMUX_TMPDIR:-/tmp}/tmux-<uid>/ for socket files — the canonical location where tmux creates per-server sockets (see tmux.c’s expand_paths + TMUX_SOCK template). Only sockets with a live listener are reported; stale inodes (a common case on long-running systems where $TMUX_TMPDIR can carry thousands of orphans) are silently filtered.

Scope caveat: custom tmux -S /some/path/... servers that live OUTSIDE $TMUX_TMPDIR are not returned by the scan alone — there is no canonical registry for arbitrary socket paths. Supply known paths via extra_socket_paths to include them in the result, or pass the path to other tools via their socket_name / socket_path parameters once known.

Parameters:

extra_socket_paths (list of str, optional) – Additional filesystem paths to probe alongside the $TMUX_TMPDIR scan. Each path is checked for liveness (UNIX connect()) and queried for server metadata. Paths that do not exist, are not sockets, or have no listener are silently skipped.

Returns:

One entry per live tmux server found. Canonical-directory results come first, followed by successful extra_socket_paths probes in the supplied order. Empty when nothing lives under $TMUX_TMPDIR and no extras are supplied or reachable.

Return type:

list[ServerInfo]

libtmux_mcp.tools.server_tools.register(mcp)

¶

function[source]

function[source]

libtmux_mcp.tools.server_tools.register(mcp)

¶

Register server-level tools with the MCP instance.

Parameters:

mcp (FastMCP)

Return type:

None

Session tools¶

MCP tools for tmux session operations.

libtmux_mcp.tools.session_tools.list_windows(session_name=None, session_id=None, socket_name=None, filters=None)

¶

function[source]

function[source]

libtmux_mcp.tools.session_tools.list_windows(session_name=None, session_id=None, socket_name=None, filters=None)

¶

List tmux windows (terminal tabs) in a session, or across the server.

Use for tmux windows — ‘current window’, ‘this tab’ (when terminal- contextual) — not browser tabs or desktop windows. Only searches window metadata (name, index, layout); to search the actual visible terminal text, use search_panes.

Parameters:

• session_name (str, optional) – Session name to look up. If omitted along with session_id, returns windows from all sessions.

• session_id (str, optional) – Session ID (e.g. ‘$1’) to look up.

• socket_name (str, optional) – tmux socket name. Defaults to LIBTMUX_SOCKET env var.

• filters (dict or str, optional) – Django-style filters as a dict (e.g. {"window_name__contains": "dev"}) or as a JSON string. Some MCP clients require the string form.

Returns:

List of serialized window objects.

Return type:

list[WindowInfo]

libtmux_mcp.tools.session_tools.get_session_info(session_id=None, session_name=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.session_tools.get_session_info(session_id=None, session_name=None, socket_name=None)

¶

Return metadata for a single tmux session (ID, name, window count, activity).

Use this instead of list_sessions + filter when you only need one session’s info. Resolves by session_id first; falls back to session_name.

Parameters:

• session_id (str, optional) – Session ID (e.g. ‘$0’).

• session_name (str, optional) – Session name.

• socket_name (str, optional) – tmux socket name.

Returns:

Serialized session metadata.

Return type:

SessionInfo

libtmux_mcp.tools.session_tools.create_window(session_name=None, session_id=None, window_name=None, start_directory=None, attach=False, direction=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.session_tools.create_window(session_name=None, session_id=None, window_name=None, start_directory=None, attach=False, direction=None, socket_name=None)

¶

Create a new window in a tmux session.

Creates a window with one pane. Use split_window to add more panes afterward.

Parameters:

• session_name (str, optional) – Session name to look up.

• session_id (str, optional) – Session ID (e.g. ‘$1’) to look up.

• window_name (str, optional) – Name for the new window.

• start_directory (str, optional) – Working directory for the new window.

• attach (bool, optional) – Whether to make the new window active.

• direction (str, optional) – Window placement direction.

• socket_name (str, optional) – tmux socket name. Defaults to LIBTMUX_SOCKET env var.

Returns:

Serialized window object.

Return type:

WindowInfo

libtmux_mcp.tools.session_tools.rename_session(new_name, session_name=None, session_id=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.session_tools.rename_session(new_name, session_name=None, session_id=None, socket_name=None)

¶

Rename a tmux session.

Use when a session’s purpose has changed. Existing pane_id references remain valid after renaming.

Parameters:

• new_name (str) – New name for the session.

• session_name (str, optional) – Current session name to look up.

• session_id (str, optional) – Session ID (e.g. ‘$1’) to look up.

• socket_name (str, optional) – tmux socket name. Defaults to LIBTMUX_SOCKET env var.

Returns:

Serialized session object.

Return type:

SessionInfo

libtmux_mcp.tools.session_tools.kill_session(session_name=None, session_id=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.session_tools.kill_session(session_name=None, session_id=None, socket_name=None)

¶

Kill a tmux session.

Destroys the session and all its windows and panes. Use kill_window to remove a single window instead. Self-kill protection prevents killing the session containing this MCP process.

Parameters:

• session_name (str, optional) – Session name to look up.

• session_id (str, optional) – Session ID (e.g. ‘$1’) to look up.

• socket_name (str, optional) – tmux socket name. Defaults to LIBTMUX_SOCKET env var.

Returns:

Confirmation message.

Return type:

str

libtmux_mcp.tools.session_tools.select_window(window_id=None, window_index=None, direction=None, session_name=None, session_id=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.session_tools.select_window(window_id=None, window_index=None, direction=None, session_name=None, session_id=None, socket_name=None)

¶

Select (focus) a tmux window by ID, index, or direction.

Use to navigate between windows. Provide window_id or window_index for direct selection, or direction for relative navigation.

Parameters:

• window_id (str, optional) – Window ID (e.g. ‘@1’) for direct selection.

• window_index (str, optional) – Window index for direct selection.

• direction (str, optional) – Relative direction: ‘next’, ‘previous’, or ‘last’.

• session_name (str, optional) – Session name for resolution.

• session_id (str, optional) – Session ID for resolution.

• socket_name (str, optional) – tmux socket name.

Returns:

The now-active window.

Return type:

WindowInfo

libtmux_mcp.tools.session_tools.register(mcp)

¶

function[source]

function[source]

libtmux_mcp.tools.session_tools.register(mcp)

¶

Register session-level tools with the MCP instance.

Parameters:

mcp (FastMCP)

Return type:

None

Window tools¶

MCP tools for tmux window operations.

libtmux_mcp.tools.window_tools.list_panes(session_name=None, session_id=None, window_id=None, window_index=None, socket_name=None, filters=None)

¶

function[source]

function[source]

libtmux_mcp.tools.window_tools.list_panes(session_name=None, session_id=None, window_id=None, window_index=None, socket_name=None, filters=None)

¶

List tmux panes (terminal multiplexer splits) in a window, session, or server.

Use for terminal panes — including ‘this pane’, ‘current pane’, ‘split pane’, ‘the bottom shell’ — not editor splits or browser panes. Only searches pane metadata (current command, title, working directory); to search the actual visible terminal text, use search_panes.

Parameters:

• session_name (str, optional) – Session name. If given without window params, lists all panes in the session.

• session_id (str, optional) – Session ID. If given without window params, lists all panes in the session.

• window_id (str, optional) – Window ID (e.g. ‘@1’). Scopes to a single window.

• window_index (str, optional) – Window index within the session. Scopes to a single window.

• socket_name (str, optional) – tmux socket name.

• filters (dict or str, optional) – Django-style filters as a dict (e.g. {"pane_current_command__contains": "vim"}) or as a JSON string. Some MCP clients require the string form.

Returns:

List of serialized pane objects.

Return type:

list[PaneInfo]

libtmux_mcp.tools.window_tools.get_window_info(window_id=None, window_index=None, session_name=None, session_id=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.window_tools.get_window_info(window_id=None, window_index=None, session_name=None, session_id=None, socket_name=None)

¶

Return metadata for a single tmux window (ID, name, layout, dimensions).

Use this instead of list_windows + filter when you only need one window’s info. Resolves the window by window_id first; falls back to window_index within a session if window_id is not given.

Parameters:

• window_id (str, optional) – Window ID (e.g. ‘@1’).

• window_index (str, optional) – Window index within the session. Requires session_name or session_id to disambiguate.

• session_name (str, optional) – Session name for window_index lookup.

• session_id (str, optional) – Session ID for window_index lookup.

• socket_name (str, optional) – tmux socket name.

Returns:

Serialized window metadata.

Return type:

WindowInfo

libtmux_mcp.tools.window_tools.split_window(pane_id=None, session_name=None, session_id=None, window_id=None, window_index=None, direction=None, size=None, start_directory=None, shell=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.window_tools.split_window(pane_id=None, session_name=None, session_id=None, window_id=None, window_index=None, direction=None, size=None, start_directory=None, shell=None, socket_name=None)

¶

Split a tmux window to create a new pane.

Creates a new pane by splitting an existing one. Use direction to choose above/below/left/right. Returns the new pane’s info including its pane_id.

Parameters:

• pane_id (str, optional) – Pane ID to split from. If given, splits adjacent to this pane.

• session_name (str, optional) – Session name.

• session_id (str, optional) – Session ID (e.g. ‘$1’).

• window_id (str, optional) – Window ID (e.g. ‘@1’).

• window_index (str, optional) – Window index within the session.

• direction (str, optional) – Split direction.

• size (str or int, optional) – Size of the new pane. Use a string with ‘%%’ suffix for percentage (e.g. ‘50%%’) or an integer for lines/columns.

• start_directory (str, optional) – Working directory for the new pane.

• shell (str, optional) – Shell command to run in the new pane.

• socket_name (str, optional) – tmux socket name.

Returns:

Serialized pane object.

Return type:

PaneInfo

libtmux_mcp.tools.window_tools.rename_window(new_name, window_id=None, window_index=None, session_name=None, session_id=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.window_tools.rename_window(new_name, window_id=None, window_index=None, session_name=None, session_id=None, socket_name=None)

¶

Rename a tmux window.

Use when a window’s purpose has changed. Existing window_id references remain valid after renaming.

Parameters:

• new_name (str) – The new name for the window.

• window_id (str, optional) – Window ID (e.g. ‘@1’).

• window_index (str, optional) – Window index within the session.

• session_name (str, optional) – Session name.

• session_id (str, optional) – Session ID.

• socket_name (str, optional) – tmux socket name.

Returns:

Serialized window object.

Return type:

WindowInfo

libtmux_mcp.tools.window_tools.kill_window(window_id, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.window_tools.kill_window(window_id, socket_name=None)

¶

Kill (close) a tmux window. Requires exact window_id (e.g. ‘@3’).

Destroys the window and all its panes. Use kill_pane to remove a single pane instead. Self-kill protection prevents killing the window containing this MCP process.

Parameters:

• window_id (str) – Window ID (e.g. ‘@1’). Required — no fallback resolution.

• socket_name (str, optional) – tmux socket name.

Returns:

Confirmation message.

Return type:

str

libtmux_mcp.tools.window_tools.select_layout(layout, window_id=None, window_index=None, session_name=None, session_id=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.window_tools.select_layout(layout, window_id=None, window_index=None, session_name=None, session_id=None, socket_name=None)

¶

Set the layout of a tmux window.

Choose from: even-horizontal, even-vertical, main-horizontal, main-vertical, or tiled. Rearranges all panes in the window.

Parameters:

• layout (str) – Layout name or custom layout string. Built-in layouts: ‘even-horizontal’, ‘even-vertical’, ‘main-horizontal’, ‘main-horizontal-mirrored’, ‘main-vertical’, ‘main-vertical-mirrored’, ‘tiled’.

• window_id (str, optional) – Window ID (e.g. ‘@1’).

• window_index (str, optional) – Window index within the session.

• session_name (str, optional) – Session name.

• session_id (str, optional) – Session ID.

• socket_name (str, optional) – tmux socket name.

Returns:

Serialized window object.

Return type:

WindowInfo

libtmux_mcp.tools.window_tools.resize_window(window_id=None, window_index=None, session_name=None, session_id=None, height=None, width=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.window_tools.resize_window(window_id=None, window_index=None, session_name=None, session_id=None, height=None, width=None, socket_name=None)

¶

Resize a tmux window.

Use to adjust the window dimensions. This affects all panes within the window.

Parameters:

• window_id (str, optional) – Window ID (e.g. ‘@1’).

• window_index (str, optional) – Window index within the session.

• session_name (str, optional) – Session name.

• session_id (str, optional) – Session ID.

• height (int, optional) – New height in lines.

• width (int, optional) – New width in columns.

• socket_name (str, optional) – tmux socket name.

Returns:

Serialized window object.

Return type:

WindowInfo

libtmux_mcp.tools.window_tools.move_window(window_id=None, window_index=None, session_name=None, session_id=None, destination_index='', destination_session=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.window_tools.move_window(window_id=None, window_index=None, session_name=None, session_id=None, destination_index='', destination_session=None, socket_name=None)

¶

Move a window to a different index or session.

Reorder windows within a session or move a window to another session.

Parameters:

• window_id (str, optional) – Window ID (e.g. ‘@1’).

• window_index (str, optional) – Window index within the session.

• session_name (str, optional) – Source session name.

• session_id (str, optional) – Source session ID.

• destination_index (str) – Target window index. Default empty string (next available).

• destination_session (str, optional) – Target session name or ID. Default is current session.

• socket_name (str, optional) – tmux socket name.

Returns:

Serialized window after move.

Return type:

WindowInfo

libtmux_mcp.tools.window_tools.register(mcp)

¶

function[source]

function[source]

libtmux_mcp.tools.window_tools.register(mcp)

¶

Register window-level tools with the MCP instance.

Parameters:

mcp (FastMCP)

Return type:

None

Pane tools¶

Pane-level MCP tools, organised by domain.

The package is structured by operation kind (io, wait, search, copy_mode, layout, lifecycle, pipe, meta). Consumers can continue to import libtmux_mcp.tools.pane_tools — re-exports below preserve the historical flat namespace so existing tests and typed imports keep working.

libtmux_mcp.tools.pane_tools.capture_pane(pane_id=None, session_name=None, session_id=None, window_id=None, start=None, end=None, max_lines=CAPTURE_DEFAULT_MAX_LINES, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.pane_tools.capture_pane(pane_id=None, session_name=None, session_id=None, window_id=None, start=None, end=None, max_lines=CAPTURE_DEFAULT_MAX_LINES, socket_name=None)

¶

Capture the visible contents of a tmux pane (terminal scrollback).

Use for tmux pane output — ‘capture the build log’, ‘what did the server print’ — not editor file contents. The tool for reading what is displayed in a terminal; use search_panes to search across multiple panes at once.

Output is tail-preserved: when the capture exceeds max_lines the oldest lines are dropped and the returned string is prefixed with a single [... truncated K lines ...] header line so the agent can tell truncation occurred and re-request with a narrower start/end window or a larger max_lines if needed. Pass max_lines=None to disable truncation entirely.

Parameters:

• pane_id (str, optional) – Pane ID (e.g. ‘%1’).

• session_name (str, optional) – Session name for pane resolution.

• session_id (str, optional) – Session ID (e.g. ‘$1’) for pane resolution.

• window_id (str, optional) – Window ID for pane resolution.

• start (int, optional) – Start line number. 0 is the first visible line. Negative values reach into scrollback history (e.g. -100 for last 100 lines).

• end (int, optional) – End line number.

• max_lines (int or None) – Maximum number of lines to return. Defaults to CAPTURE_DEFAULT_MAX_LINES. Pass None to return the full capture with no truncation.

• socket_name (str, optional) – tmux socket name.

Returns:

Captured pane content as text. When truncated, the first line is a [... truncated K lines ...] marker.

Return type:

str

async libtmux_mcp.tools.pane_tools.capture_since(cursor=None, pane_id=None, session_name=None, session_id=None, window_id=None, max_lines=CAPTURE_SINCE_DEFAULT_MAX_LINES, max_bytes=CAPTURE_SINCE_DEFAULT_MAX_BYTES, socket_name=None)

¶

async function[source]

async function[source]

async libtmux_mcp.tools.pane_tools.capture_since(cursor=None, pane_id=None, session_name=None, session_id=None, window_id=None, max_lines=CAPTURE_SINCE_DEFAULT_MAX_LINES, max_bytes=CAPTURE_SINCE_DEFAULT_MAX_BYTES, socket_name=None)

¶

Capture new tmux terminal scrollback since the previous cursor.

Use for observation-first workflows: tailing a shell, watching a long-running command, or repeatedly checking a tmux workspace pane without re-sending the same visible screen every turn. The first call with cursor=None returns the current visible pane and an opaque cursor. Later calls pass that cursor back and receive only rows written or rewritten after the cursor, as long as tmux still retains the required scrollback history.

If tmux history was cleared or trimmed before the cursor anchor, the tool returns the current visible pane with lines_missed=True and a fresh cursor. Malformed cursors, cursors for a different pane, pane death, and pane respawn fail with ExpectedToolError so agents do not accidentally observe the wrong process.

Parameters:

• cursor (str, optional) – Opaque cursor returned by a prior capture_since call. When omitted, the tool captures the current visible screen and starts a new cursor.

• pane_id (str, optional) – Pane ID (e.g. ‘%1’). Optional when cursor is supplied; the cursor carries the original pane id.

• session_name (str, optional) – Session name for pane resolution.

• session_id (str, optional) – Session ID (e.g. ‘$1’) for pane resolution.

• window_id (str, optional) – Window ID for pane resolution.

• max_lines (int or None) – Maximum number of lines to return. Defaults to CAPTURE_SINCE_DEFAULT_MAX_LINES. Pass None to disable line truncation.

• max_bytes (int or None) – Maximum UTF-8 bytes to return across lines. Defaults to CAPTURE_SINCE_DEFAULT_MAX_BYTES. Pass None to disable byte truncation.

• socket_name (str, optional) – tmux socket name.

Returns:

Structured lines, cursor, elapsed time, and truncation/loss metadata.

Return type:

CaptureSinceResult

libtmux_mcp.tools.pane_tools.clear_pane(pane_id=None, session_name=None, session_id=None, window_id=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.pane_tools.clear_pane(pane_id=None, session_name=None, session_id=None, window_id=None, socket_name=None)

¶

Clear the contents of a tmux pane.

Use before a fresh run_command call or raw-input observation workflow when prior scrollback would make the result harder to inspect.

Parameters:

• pane_id (str, optional) – Pane ID (e.g. ‘%1’).

• session_name (str, optional) – Session name for pane resolution.

• session_id (str, optional) – Session ID (e.g. ‘$1’) for pane resolution.

• window_id (str, optional) – Window ID for pane resolution.

• socket_name (str, optional) – tmux socket name.

Returns:

Confirmation message.

Return type:

str

libtmux_mcp.tools.pane_tools.display_message(format_string, pane_id=None, session_name=None, session_id=None, window_id=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.pane_tools.display_message(format_string, pane_id=None, session_name=None, session_id=None, window_id=None, socket_name=None)

¶

Evaluate a tmux format string against a target and return the expanded value.

Read-only introspection tool — expands any tmux format variable against a target pane and returns the substituted text. Use this when no dedicated tool covers the field you want, e.g. ‘#{window_zoomed_flag}’, ‘#{pane_dead}’, ‘#{client_activity}’.

Parameters:

• format_string (str) – tmux format string (e.g. ‘#{cursor_x} #{cursor_y}’).

• pane_id (str, optional) – Pane ID (e.g. ‘%1’).

• session_name (str, optional) – Session name for pane resolution.

• session_id (str, optional) – Session ID for pane resolution.

• window_id (str, optional) – Window ID for pane resolution.

• socket_name (str, optional) – tmux socket name.

Returns:

Expanded format string result.

Return type:

str

libtmux_mcp.tools.pane_tools.enter_copy_mode(pane_id=None, scroll_up=None, session_name=None, session_id=None, window_id=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.pane_tools.enter_copy_mode(pane_id=None, scroll_up=None, session_name=None, session_id=None, window_id=None, socket_name=None)

¶

Enter copy mode in a tmux pane, optionally scrolling up.

Use to navigate scrollback history. After entering copy mode, use snapshot_pane to read the scroll_position and content.

Parameters:

• pane_id (str, optional) – Pane ID (e.g. ‘%1’).

• scroll_up (int, optional) – Number of lines to scroll up immediately after entering copy mode.

• session_name (str, optional) – Session name for pane resolution.

• session_id (str, optional) – Session ID for pane resolution.

• window_id (str, optional) – Window ID for pane resolution.

• socket_name (str, optional) – tmux socket name.

Returns:

Serialized pane info.

Return type:

PaneInfo

libtmux_mcp.tools.pane_tools.exit_copy_mode(pane_id=None, session_name=None, session_id=None, window_id=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.pane_tools.exit_copy_mode(pane_id=None, session_name=None, session_id=None, window_id=None, socket_name=None)

¶

Exit copy mode in a tmux pane.

Returns the pane to normal mode. Use after scrolling through scrollback history.

Parameters:

• pane_id (str, optional) – Pane ID (e.g. ‘%1’).

• session_name (str, optional) – Session name for pane resolution.

• session_id (str, optional) – Session ID for pane resolution.

• window_id (str, optional) – Window ID for pane resolution.

• socket_name (str, optional) – tmux socket name.

Returns:

Serialized pane info.

Return type:

PaneInfo

libtmux_mcp.tools.pane_tools.find_pane_by_position(corner, window_id=None, window_index=None, session_name=None, session_id=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.pane_tools.find_pane_by_position(corner, window_id=None, window_index=None, session_name=None, session_id=None, socket_name=None)

¶

Find the pane occupying a corner of a tmux window.

Composes the four pane_at_* predicates so callers can target a layout-relative position (e.g. “the bottom-right pane”) in one round-trip instead of listing every pane and computing the geometry. Resolves the window the same way as the other window-scoped tools.

Parameters:

• corner (str) – One of 'top-left', 'top-right', 'bottom-left', 'bottom-right'.

• window_id (str, optional) – Window ID (e.g. ‘@1’).

• window_index (str, optional) – Window index. Requires session_name or session_id.

• session_name (str, optional) – Session name.

• session_id (str, optional) – Session ID.

• socket_name (str, optional) – tmux socket name.

Returns:

Serialized pane occupying the requested corner.

Return type:

PaneInfo

Raises:

ExpectedToolError – If no pane satisfies both edge predicates for that corner — in practice only possible for layouts tmux itself produced via custom layout strings; the built-in layouts always have a pane at every corner.

libtmux_mcp.tools.pane_tools.get_pane_info(pane_id=None, session_name=None, session_id=None, window_id=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.pane_tools.get_pane_info(pane_id=None, session_name=None, session_id=None, window_id=None, socket_name=None)

¶

Get detailed information about a tmux pane.

Use this for metadata (PID, path, dimensions) without reading terminal content. To read what is displayed in the pane, use capture_pane instead.

Parameters:

• pane_id (str, optional) – Pane ID (e.g. ‘%1’).

• session_name (str, optional) – Session name for pane resolution.

• session_id (str, optional) – Session ID (e.g. ‘$1’) for pane resolution.

• window_id (str, optional) – Window ID for pane resolution.

• socket_name (str, optional) – tmux socket name.

Returns:

Serialized pane details.

Return type:

PaneInfo

libtmux_mcp.tools.pane_tools.kill_pane(pane_id, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.pane_tools.kill_pane(pane_id, socket_name=None)

¶

Kill (close) a tmux pane. Requires exact pane_id (e.g. ‘%5’).

Use to clean up panes no longer needed. To remove an entire window and all its panes, use kill_window instead.

Parameters:

• pane_id (str) – Pane ID (e.g. ‘%1’). Required — no fallback resolution.

• socket_name (str, optional) – tmux socket name.

Returns:

Confirmation message.

Return type:

str

libtmux_mcp.tools.pane_tools.paste_text(text, pane_id=None, bracket=True, session_name=None, session_id=None, window_id=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.pane_tools.paste_text(text, pane_id=None, bracket=True, session_name=None, session_id=None, window_id=None, socket_name=None)

¶

Paste multi-line text into a pane using tmux paste buffers.

Uses tmux’s load-buffer and paste-buffer for clean multi-line input, avoiding the issues of sending text line-by-line via send_keys. Supports bracketed paste mode for terminals that handle it.

When to use this vs. load_buffer + paste_buffer: paste_text is the fire-and-forget path — the buffer is created, pasted, and deleted in one call. Use load_buffer + paste_buffer when you need to stage content first, paste it into multiple panes, or inspect it with show_buffer before pasting.

Parameters:

• text (str) – The text to paste.

• pane_id (str, optional) – Pane ID (e.g. ‘%1’).

• bracket (bool) – Whether to use bracketed paste mode. Default True. Bracketed paste wraps the text in escape sequences that tell the terminal “this is pasted text, not typed input”.

• session_name (str, optional) – Session name for pane resolution.

• session_id (str, optional) – Session ID for pane resolution.

• window_id (str, optional) – Window ID for pane resolution.

• socket_name (str, optional) – tmux socket name.

Returns:

Confirmation message.

Return type:

str

libtmux_mcp.tools.pane_tools.pipe_pane(pane_id=None, output_path=None, append=True, session_name=None, session_id=None, window_id=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.pane_tools.pipe_pane(pane_id=None, output_path=None, append=True, session_name=None, session_id=None, window_id=None, socket_name=None)

¶

Log a pane’s live output to a file (or stop an active log).

Streams everything written to the pane (stdout plus terminal control sequences) into a file on disk — the common use is output_path="/tmp/pane.log" to capture scrollback continuously while the agent watches for errors. When output_path is given, starts logging; when output_path is None, stops any active pipe for the pane.

Warning

This tool writes to arbitrary filesystem paths chosen by the MCP client. There is no allow-list; the server will create files anywhere the server process has write access. Treat this as elevated-risk even though it sits in the mutating safety tier — it is the broadest-reach tool in that tier. If you run libtmux-mcp on untrusted input, consider LIBTMUX_SAFETY=readonly or run the server under a user with a scoped home directory. See Safety tiers for the full footgun list.

Parameters:

• pane_id (str, optional) – Pane ID (e.g. ‘%1’).

• output_path (str, optional) – File path to write output to. None stops piping.

• append (bool) – Whether to append to the file. Default True. If False, overwrites.

• session_name (str, optional) – Session name for pane resolution.

• session_id (str, optional) – Session ID for pane resolution.

• window_id (str, optional) – Window ID for pane resolution.

• socket_name (str, optional) – tmux socket name.

Returns:

Confirmation message.

Return type:

str

libtmux_mcp.tools.pane_tools.register(mcp)

¶

function[source]

function[source]

libtmux_mcp.tools.pane_tools.register(mcp)

¶

Register pane-level tools with the MCP instance.

Parameters:

mcp (FastMCP)

Return type:

None

libtmux_mcp.tools.pane_tools.resize_pane(pane_id=None, session_name=None, session_id=None, window_id=None, height=None, width=None, zoom=None, socket_name=None)

¶

function[source]

function[source]

libtmux_mcp.tools.pane_tools.resize_pane(pane_id=None, session_name=None, session_id=None, window_id=None, height=None, width=None, zoom=None, socket_name=None)

¶

Resize a tmux pane.

Use when adjusting layout for better readability or to fit content.

Parameters:

• pane_id (str, optional) – Pane ID (e.g. ‘%1’).

• session_name (str, optional) – Session name for pane resolution.

• session_id (str, optional) – Session ID (e.g. ‘$1’) for pane resolution.

• window_id (str, optional) – Window ID for pane resolution.

• height (int, optional) – New height in lines.

• width (int, optional) – New width in columns.

• zoom (bool, optional) – Toggle pane zoom. If True, zoom the pane. If False, unzoom.

• socket_name (str, optional) – tmux socket name.

Returns:

Serialized pane object.

Return type:

PaneInfo