libtmux_mcp.tools.pane_tools.respawn_pane

API reference · Markdown

libtmux_mcp.tools.pane_tools.respawn_pane ( pane_id : str , kill : bool = True , shell : str | None = None , start_directory : str | None = None , environment : dict[str, str] | str | None = None , socket_name : str | None = None , suppress_persistent_history : bool = False ) → PaneInfo

function [source] ¶

function [source] ¶

libtmux_mcp.tools.pane_tools.respawn_pane

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 | None ) – 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 | None ) – Existing directory to start in. ~ expands; a relative path resolves against the MCP server process's directory.

• environment ( dict[str, str] | str | None ) – 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 supplied in a mapping 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. A JSON object string is redacted as one scalar digest, so its keys are not retained in the audit record. 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 | None ) – tmux socket name.

• suppress_persistent_history ( bool ) – Whether to suppress persistent history for the spawned shell. Defaults to False for MCP and direct Python calls. This per-call option does not inherit LIBTMUX_SUPPRESS_HISTORY. Startup files may override these controls.

Returns

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