Tools

Server tools

MCP tools for tmux server operations.

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

List all tmux sessions.

Return type:

list[SessionInfo]

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)

Create a new tmux session.

Return type:

SessionInfo

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, optional) – Environment variables to set.

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

Kill the tmux server and all its sessions.

Return type:

str

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)

Get information about the tmux server.

Return type:

ServerInfo

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.register(mcp)

Register server-level tools with the MCP instance.

Return type:

None

Parameters:

mcp (FastMCP)

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)

List windows in a tmux session, or all windows across sessions.

Only searches window metadata (name, index, layout). To search the actual text visible in terminal panes, use search_panes instead.

Return type:

list[WindowInfo]

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

Return type:

WindowInfo

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)

Rename a tmux session.

Return type:

SessionInfo

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)

Kill a tmux session.

Return type:

str

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.register(mcp)

Register session-level tools with the MCP instance.

Return type:

None

Parameters:

mcp (FastMCP)

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)

List panes in a tmux window, session, or across the entire server.

Only searches pane metadata (current command, title, working directory). To search the actual text visible in terminal panes, use search_panes instead.

Return type:

list[PaneInfo]

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

Return type:

PaneInfo

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)

Rename a tmux window.

Return type:

WindowInfo

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)

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

Return type:

str

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)

Set the layout of a tmux window.

Return type:

WindowInfo

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)

Resize a tmux window.

Return type:

WindowInfo

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.register(mcp)

Register window-level tools with the MCP instance.

Return type:

None

Parameters:

mcp (FastMCP)

Pane tools

MCP tools for tmux pane operations.

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.

Return type:

str

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.capture_pane(pane_id=None, session_name=None, session_id=None, window_id=None, start=None, end=None, socket_name=None)

Capture the visible contents of a tmux pane.

This is the tool for reading what is displayed in a terminal. Use search_panes to search for text across multiple panes at once.

Return type:

str

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.

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

Returns:

Captured pane content as text.

Return type:

str

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.

Return type:

PaneInfo

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.kill_pane(pane_id, socket_name=None)

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

Return type:

str

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

Return type:

PaneInfo

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

Return type:

PaneInfo

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.clear_pane(pane_id=None, session_name=None, session_id=None, window_id=None, socket_name=None)

Clear the contents of a tmux pane.

Return type:

str

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.search_panes(pattern, regex=False, session_name=None, session_id=None, match_case=False, content_start=None, content_end=None, socket_name=None)

Search for text across all pane contents.

Use this when users ask what panes ‘contain’, ‘mention’, or ‘show’. Searches each pane’s visible content and returns panes where the pattern is found, with matching lines.

Return type:

list[PaneContentMatch]

Parameters:

• pattern (str) – Text to search for in pane contents. 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).

• session_name (str, optional) – Limit search to panes in this session.

• session_id (str, optional) – Limit search to panes in this session (by ID).

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

Returns:

Panes with matching content, including matched lines.

Return type:

list[PaneContentMatch]

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)

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.

Return type:

WaitForTextResult

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.

Returns:

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

Return type:

WaitForTextResult

libtmux_mcp.tools.pane_tools.register(mcp)

Register pane-level tools with the MCP instance.

Return type:

None

Parameters:

mcp (FastMCP)

Option tools

MCP tools for tmux option management.

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

Show a tmux option value.

Return type:

OptionResult

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)

Set a tmux option value.

Return type:

OptionSetResult

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)

Register option tools with the MCP instance.

Return type:

None

Parameters:

mcp (FastMCP)

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)

Show tmux environment variables.

Return type:

EnvironmentResult

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)

Set a tmux environment variable.

Return type:

EnvironmentSetResult

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)

Register environment tools with the MCP instance.

Return type:

None

Parameters:

mcp (FastMCP)