Tools

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({'list_servers'})
data
data
libtmux_mcp.tools.server_tools.SOCKET_NAME_EXEMPT: frozenset[str] = frozenset({'list_servers'})

Tools that intentionally do NOT accept socket_name because they discover or enumerate sockets themselves rather than connecting to a known one. 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

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 send_keys + capture_pane to get a clean capture without prior output. Note: this is two tmux commands with a brief gap — not fully atomic.

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:

ToolError – 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

libtmux_mcp.tools.pane_tools.respawn_pane(pane_id, kill=True, shell=None, start_directory=None, environment=None, socket_name=None)
function[source]
function[source]
libtmux_mcp.tools.pane_tools.respawn_pane(pane_id, kill=True, shell=None, start_directory=None, environment=None, socket_name=None)

Restart a pane’s process in place, preserving pane_id and layout.

Use when a shell wedges (hung REPL, runaway process, bad terminal mode). The alternative — kill_pane + split_window — destroys pane_id references the agent may still be holding, and rearranges the layout. respawn-pane preserves both.

With kill=True (the default), tmux kills the existing process before respawning. Optional shell replaces the command tmux relaunches; start_directory sets the working directory for the new process; environment sets per-process environment variables for the relaunched command (one -e KEY=VALUE flag per entry).

pane_id is required — sibling pane tools accept a hierarchical fallback (session_name / window_id / pane_index) that resolves to “first pane in session/window”, but combined with default kill=True that fallback could silently kill an unrelated process. The signature deliberately omits the resolver fields so the FastMCP schema rejects them at the framework boundary. Resolve via list_panes first.

Tip: call get_pane_info first if you need to capture pane_current_command before respawn — the new process loses its argv. Omitting shell makes tmux replay the original argv (good default for shells; may differ for processes spawned via custom shell at split time).

Parameters:

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

  • kill (bool) – When True (default), pass -k to tmux so the current process is killed before respawning. When False, respawn fails if the pane already has a running process.

  • shell (str, optional) – Replacement command for tmux to launch. When omitted, tmux replays the original argv (good default for shells; may differ for processes spawned via custom shell at split time). Matches the shell parameter on split_window() and the eventual upstream Pane.respawn(shell=) API.

  • start_directory (str, optional) – Working directory for the relaunched command (maps to respawn-pane -c).

  • environment (dict[str, str], optional) – Environment variables to set for the relaunched process. Each item becomes one -e KEY=VALUE flag (tmux’s cmd-respawn-pane.c supports the flag repeatedly). Values are redacted in the audit log on a per-key basis — keys like DATABASE_URL remain visible but their values are replaced by {len, sha256_prefix} digests. Note that the values may still appear briefly in the OS process table while tmux spawns the new process; do not pass long-lived secrets here when a host-resident agent or other tenant could observe ps.

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

Returns:

Serialized pane metadata after respawn. The pane_id is preserved; pane_pid reflects the new process.

Return type:

PaneInfo

libtmux_mcp.tools.pane_tools.search_panes(pattern, regex=False, session_name=None, session_id=None, match_case=False, content_start=None, content_end=None, max_matched_lines_per_pane=SEARCH_DEFAULT_MAX_LINES_PER_PANE, limit=SEARCH_DEFAULT_LIMIT, offset=0, socket_name=None)
function[source]
function[source]
libtmux_mcp.tools.pane_tools.search_panes(pattern, regex=False, session_name=None, session_id=None, match_case=False, content_start=None, content_end=None, max_matched_lines_per_pane=SEARCH_DEFAULT_MAX_LINES_PER_PANE, limit=SEARCH_DEFAULT_LIMIT, offset=0, socket_name=None)

Search visible terminal text across all tmux panes.

Use when the user asks what panes ‘contain’, ‘mention’, or ‘show’ — e.g. ‘find the pane with the pytest failure’. Searches each pane’s visible terminal scrollback content (not editor or browser text) and returns panes where the pattern is found, with matching lines.

Bounded output contract

The result is paginated at the pane level. The matching panes are sorted by pane_id and then sliced with offset / limit. Each matching pane’s matched_lines is further tail-truncated to at most max_matched_lines_per_pane entries (most-recent lines preserved). Caps apply only to the slow path (pane.capture_pane() + Python regex); the tmux fast path at #{C:pattern} returns pane IDs only and is already bounded by tmux.

param pattern:

Text to search for in pane contents. Treated as literal text by default. Set regex=True to interpret as a regular expression.

type pattern:

str

param regex:

Whether to interpret pattern as a regular expression. Default False (literal text matching).

type regex:

bool

param session_name:

Limit search to panes in this session.

type session_name:

str, optional

param session_id:

Limit search to panes in this session (by ID).

type session_id:

str, optional

param match_case:

Whether to match case. Default False (case-insensitive).

type match_case:

bool

param content_start:

Start line for capture. Negative values reach into scrollback.

type content_start:

int, optional

param content_end:

End line for capture.

type content_end:

int, optional

param max_matched_lines_per_pane:

Per-pane cap on matched_lines. Defaults to SEARCH_DEFAULT_MAX_LINES_PER_PANE.

type max_matched_lines_per_pane:

int

param limit:

Maximum matching panes returned on this call. Defaults to SEARCH_DEFAULT_LIMIT. Pass None to disable the cap.

type limit:

int or None

param offset:

Skip this many matching panes from the start. Use with limit for pagination.

type offset:

int

param socket_name:

tmux socket name.

type socket_name:

str, optional

returns:

Paginated match list with truncated / truncated_panes / total_panes_matched / offset / limit fields.

rtype:

SearchPanesResult

Parameters:
Return type:

SearchPanesResult

libtmux_mcp.tools.pane_tools.select_pane(pane_id=None, direction=None, window_id=None, window_index=None, session_name=None, session_id=None, socket_name=None)
function[source]
function[source]
libtmux_mcp.tools.pane_tools.select_pane(pane_id=None, direction=None, window_id=None, window_index=None, session_name=None, session_id=None, socket_name=None)

Select (focus) a tmux pane by ID or direction.

Use this to navigate between panes. Provide either pane_id for direct selection, or direction for relative navigation within a window.

Parameters:

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

  • direction (str, optional) – Relative direction: ‘up’, ‘down’, ‘left’, ‘right’, ‘last’ (previously active), ‘next’, or ‘previous’.

  • window_id (str, optional) – Window ID for directional navigation scope.

  • window_index (str, optional) – Window index for directional navigation scope.

  • 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 pane.

Return type:

PaneInfo

libtmux_mcp.tools.pane_tools.send_keys(keys, pane_id=None, session_name=None, session_id=None, window_id=None, enter=True, literal=False, suppress_history=False, socket_name=None)
function[source]
function[source]
libtmux_mcp.tools.pane_tools.send_keys(keys, pane_id=None, session_name=None, session_id=None, window_id=None, enter=True, literal=False, suppress_history=False, socket_name=None)

Send keys (commands or text) to a tmux pane.

After sending, use wait_for_text to block until the command completes, or capture_pane to read the result. Do not capture_pane immediately — there is a race condition.

Parameters:

  • keys (str) – The keys or text to send.

  • 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.

  • enter (bool) – Whether to press Enter after sending keys. Default True.

  • literal (bool) – Whether to send keys literally (no tmux interpretation). Default False.

  • suppress_history (bool) – Whether to suppress shell history by prepending a space. Only works in shells that support HISTCONTROL. Default False.

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

Returns:

Confirmation message.

Return type:

str

libtmux_mcp.tools.pane_tools.set_pane_title(title, pane_id=None, session_name=None, session_id=None, window_id=None, socket_name=None)
function[source]
function[source]
libtmux_mcp.tools.pane_tools.set_pane_title(title, pane_id=None, session_name=None, session_id=None, window_id=None, socket_name=None)

Set the title of a tmux pane.

Use titles to label panes for later identification via list_panes or get_pane_info.

Parameters:

  • title (str) – The new pane title.

  • 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 object.

Return type:

PaneInfo

libtmux_mcp.tools.pane_tools.snapshot_pane(pane_id=None, session_name=None, session_id=None, window_id=None, max_lines=CAPTURE_DEFAULT_MAX_LINES, socket_name=None)
function[source]
function[source]
libtmux_mcp.tools.pane_tools.snapshot_pane(pane_id=None, session_name=None, session_id=None, window_id=None, max_lines=CAPTURE_DEFAULT_MAX_LINES, socket_name=None)

Snapshot a tmux pane: visible terminal output, cursor, mode, scroll.

Use for terminal-contents inspection — ‘what’s in my pane’, ‘the current shell output’ — not editor panes or browser viewports. Returns everything capture_pane and get_pane_info return, plus cursor position, copy-mode state, and scroll position — in a single call. Prefer this over separate capture_pane + get_pane_info calls when you need to reason about cursor location or pane mode.

The content field is tail-preserved: when the captured pane exceeds max_lines, the oldest lines are dropped and the result is reported via content_truncated / content_truncated_lines fields on the returned PaneSnapshot. Pass max_lines=None to opt out of 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.

  • max_lines (int or None) – Maximum number of content lines to return. Defaults to libtmux_mcp.tools.pane_tools.io.CAPTURE_DEFAULT_MAX_LINES. Pass None to return the full capture untrimmed.

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

Returns:

Rich snapshot with content, cursor, mode, and scroll state. When the capture is trimmed, content_truncated is True and content_truncated_lines gives the number of dropped head lines; content itself carries no marker header.

Return type:

PaneSnapshot

libtmux_mcp.tools.pane_tools.swap_pane(source_pane_id, target_pane_id, socket_name=None)
function[source]
function[source]
libtmux_mcp.tools.pane_tools.swap_pane(source_pane_id, target_pane_id, socket_name=None)

Swap the positions of two panes.

Exchanges the visual positions of two panes. Both panes must exist. Use this to rearrange pane layout without changing content.

Parameters:

  • source_pane_id (str) – Pane ID of the first pane (e.g. ‘%1’).

  • target_pane_id (str) – Pane ID of the second pane (e.g. ‘%2’).

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

Returns:

The source pane after swap (now in target’s position).

Return type:

PaneInfo

async libtmux_mcp.tools.pane_tools.wait_for_content_change(pane_id=None, session_name=None, session_id=None, window_id=None, timeout=8.0, interval=0.05, socket_name=None, ctx=None)
async function[source]
async function[source]
async libtmux_mcp.tools.pane_tools.wait_for_content_change(pane_id=None, session_name=None, session_id=None, window_id=None, timeout=8.0, interval=0.05, socket_name=None, ctx=None)

Wait for any content change in a tmux pane.

Captures the current pane content, then polls until the content differs or the timeout is reached. Use this after send_keys when you don’t know what the output will be — it waits for “something happened” rather than a specific pattern.

Emits fastmcp.Context.report_progress() each tick when a Context is injected, so clients can render a progress indicator during the wait.

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.

  • timeout (float) – Maximum seconds to wait. Default 8.0.

  • interval (float) – Seconds between polls. Default 0.05 (50ms).

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

  • ctx (fastmcp.Context, optional) – FastMCP context for progress notifications. Omitted in tests.

Returns:

Result with changed status and timing info.

Return type:

ContentChangeResult

Notes

Safety tier. Tagged readonly because the tool observes pane state without mutating it. Readonly clients may therefore block for the caller-supplied timeout (default 8 s, caller may pass larger values). The capture call runs on the asyncio default thread-pool executor, whose size caps concurrent waits (min(32, os.cpu_count() + 4) on CPython); a malicious readonly client could saturate that pool with long-timeout calls. If you need to rate-limit wait tools, do it at the transport layer or with dedicated middleware.

async libtmux_mcp.tools.pane_tools.wait_for_text(pattern, regex=False, pane_id=None, session_name=None, session_id=None, window_id=None, timeout=8.0, interval=0.05, match_case=False, content_start=None, content_end=None, socket_name=None, ctx=None)
async function[source]
async function[source]
async libtmux_mcp.tools.pane_tools.wait_for_text(pattern, regex=False, pane_id=None, session_name=None, session_id=None, window_id=None, timeout=8.0, interval=0.05, match_case=False, content_start=None, content_end=None, socket_name=None, ctx=None)

Wait for text to appear in a tmux pane.

Polls the pane content at regular intervals until the pattern is found or the timeout is reached. Use this instead of polling capture_pane manually — it saves agent tokens and turns.

When a fastmcp.Context is available, this tool emits periodic ctx.report_progress notifications so MCP clients can show a “polling pane X… (elapsed/timeout)” indicator during long waits. Progress notifications never block the timeout contract — if the client connection is gone the progress call is suppressed and polling continues.

Parameters:

  • pattern (str) – Text to wait for. Treated as literal text by default. Set regex=True to interpret as a regular expression.

  • regex (bool) – Whether to interpret pattern as a regular expression. Default False (literal text matching).

  • 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.

  • timeout (float) – Maximum seconds to wait. Default 8.0.

  • interval (float) – Seconds between polls. Default 0.05 (50ms).

  • match_case (bool) – Whether to match case. Default False (case-insensitive).

  • content_start (int, optional) – Start line for capture. Negative values reach into scrollback.

  • content_end (int, optional) – End line for capture.

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

  • ctx (fastmcp.Context, optional) – FastMCP context; when injected the tool reports progress to the client. Omitted in tests.

Returns:

Result with found status, matched lines, and timing info.

Return type:

WaitForTextResult

Notes

Safety tier. Tagged readonly because the tool observes pane state without mutating it. Readonly clients may therefore block for the caller-supplied timeout (default 8 s, caller may pass larger values). The capture call runs on the asyncio default thread-pool executor, whose size caps concurrent waits (min(32, os.cpu_count() + 4) on CPython); a malicious readonly client could saturate that pool with long-timeout calls. If you need to rate-limit wait tools, do it at the transport layer or with dedicated middleware.

Option tools

MCP tools for tmux option management.

libtmux_mcp.tools.option_tools._resolve_option_target(socket_name, scope, target)
function[source]
function[source]
libtmux_mcp.tools.option_tools._resolve_option_target(socket_name, scope, target)

Resolve the target object and scope for option operations.

Parameters:
Return type:

tuple[OptionsMixin, OptionScope | None]

libtmux_mcp.tools.option_tools.show_option(option, scope=None, target=None, global_=False, socket_name=None)
function[source]
function[source]
libtmux_mcp.tools.option_tools.show_option(option, scope=None, target=None, global_=False, socket_name=None)

Show a tmux option value.

Use to check tmux configuration values such as history-limit, mouse support, or status bar settings.

Parameters:

  • option (str) – The tmux option name to query.

  • scope (str, optional) – Option scope.

  • target (str, optional) – Target identifier. For session scope: session name (e.g. ‘mysession’). For window scope: window ID (e.g. ‘@1’). For pane scope: pane ID (e.g. ‘%1’). Requires scope.

  • global (bool) – Whether to query the global option.

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

  • global_ (bool)

Returns:

Option name and its value.

Return type:

OptionResult

libtmux_mcp.tools.option_tools.set_option(option, value, scope=None, target=None, global_=False, socket_name=None)
function[source]
function[source]
libtmux_mcp.tools.option_tools.set_option(option, value, scope=None, target=None, global_=False, socket_name=None)

Set a tmux option value.

Use to change tmux behavior at runtime. Common uses: adjusting history-limit, enabling mouse support, changing status bar format.

Parameters:

  • option (str) – The tmux option name to set.

  • value (str) – The value to set.

  • scope (str, optional) – Option scope.

  • target (str, optional) – Target identifier. For session scope: session name (e.g. ‘mysession’). For window scope: window ID (e.g. ‘@1’). For pane scope: pane ID (e.g. ‘%1’). Requires scope.

  • global (bool) – Whether to set the global option.

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

  • global_ (bool)

Returns:

Confirmation with option name, value, and status.

Return type:

OptionSetResult

libtmux_mcp.tools.option_tools.register(mcp)
function[source]
function[source]
libtmux_mcp.tools.option_tools.register(mcp)

Register option tools with the MCP instance.

Parameters:

mcp (FastMCP)

Return type:

None

Environment tools

MCP tools for tmux environment variable management.

libtmux_mcp.tools.env_tools.show_environment(session_name=None, session_id=None, socket_name=None)
function[source]
function[source]
libtmux_mcp.tools.env_tools.show_environment(session_name=None, session_id=None, socket_name=None)

Show tmux environment variables.

Use to inspect tmux environment variables that affect child processes.

Parameters:

  • session_name (str, optional) – Session name to query environment for.

  • session_id (str, optional) – Session ID to query environment for.

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

Returns:

Environment variable mapping.

Return type:

EnvironmentResult

libtmux_mcp.tools.env_tools.set_environment(name, value, session_name=None, session_id=None, socket_name=None)
function[source]
function[source]
libtmux_mcp.tools.env_tools.set_environment(name, value, session_name=None, session_id=None, socket_name=None)

Set a tmux environment variable.

Use to set variables that will be inherited by new panes and windows. Changes do not affect already-running processes.

Warning

Values set here propagate into every shell tmux later spawns in the targeted scope — including panes the user opens manually, not just panes the agent drives. A caller that writes PATH, LD_PRELOAD, or AWS_* variables can influence future commands the human user types directly. Treat this as elevated-risk within the mutating safety tier. The audit log redacts the value argument, but the side effects persist on disk/memory until tmux is restarted. Prefer env VAR=value command via send_keys() when you only need the override for a single command. See Safety tiers.

Parameters:

  • name (str) – Environment variable name.

  • value (str) – Environment variable value.

  • session_name (str, optional) – Session name to set environment for.

  • session_id (str, optional) – Session ID to set environment for.

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

Returns:

Confirmation with variable name, value, and status.

Return type:

EnvironmentSetResult

libtmux_mcp.tools.env_tools.register(mcp)
function[source]
function[source]
libtmux_mcp.tools.env_tools.register(mcp)

Register environment tools with the MCP instance.

Parameters:

mcp (FastMCP)

Return type:

None