# respawn_pane Source: https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/ > Restart a pane's process in place, preserving pane_id and layout. tool MCPstable MCP is in development Server behavior and tool contracts may change. Tool availability depends on the server configuration. * **respawn_pane**( [environment](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fenvironment)?: [Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [kill](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fkill)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), [pane_id](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fpane_id): [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)"), [shell](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fshell)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [socket_name](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fsocket_name)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [start_directory](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fstart_directory)?: [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)"), [suppress_persistent_history](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fsuppress_persistent_history)?: [boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)"), ) tool \[[source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L121)][¶](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.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](https://libtmux.org/en/py/stable/mcp/tools/kill_pane/) + [split_window](https://libtmux.org/en/py/stable/mcp/tools/split_window/) — destroys pane_id references the agent may still be holding, and rearranges the layout. [respawn-pane](https://libtmux.org/en/tmux/latest/manual/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`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_id/) is required — sibling pane tools accept a hierarchical fallback ([`session_name`](https://libtmux.org/en/tmux/latest/catalog/formats/session_name/) / [`window_id`](https://libtmux.org/en/tmux/latest/catalog/formats/window_id/) / [`pane_index`](https://libtmux.org/en/tmux/latest/catalog/formats/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`](https://libtmux.org/en/py/stable/mcp/tools/list_panes/) first. Tip: call [`get_pane_info`](https://libtmux.org/en/py/stable/mcp/tools/get_pane_info/) first if you need to capture [`pane_current_command`](https://libtmux.org/en/tmux/latest/catalog/formats/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). * MCP request method `tools/call` Send `respawn_pane` as the tool name, with the arguments below. ## Arguments[#](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.parameters) * **[`environment`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fenvironment)**? = `null` ([Record](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)")\ | [string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) 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`. * **[`kill`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fkill)**? = `true` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) 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. * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID (e.g. ‘%1’). Required. * **[`shell`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fshell)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) 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`](https://libtmux.org/en/py/stable/mcp/tools/split_window/) and the eventual upstream `Pane.respawn(shell=)` API. * **[`socket_name`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fsocket_name)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) tmux socket name. * **[`start_directory`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fstart_directory)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Existing directory to start in. `~` expands; a relative path resolves against the MCP server process’s directory. * **[`suppress_persistent_history`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.input%2Fproperties%2Fsuppress_persistent_history)**? = `false` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)")) 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. No other arguments are accepted. ## Result[#](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.result) Returns [object](https://json-schema.org/understanding-json-schema/reference/object "object (JSON Schema)") * **[`is_caller`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fis_caller)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) MCP caller identity for this pane. `True` when the pane matches the caller’s `TMUX_PANE` *and* lives on the same tmux socket as the caller’s `TMUX` (verified via socket realpath); `False` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; `None` when the MCP process is not running inside tmux at all. * **[`pane_active`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_active)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Active flag (‘1’ or ‘0’) * **[`pane_at_bottom`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_at_bottom)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s bottom edge. * **[`pane_at_left`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_at_left)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s left edge. * **[`pane_at_right`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_at_right)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s right edge. * **[`pane_at_top`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_at_top)**? = `null` ([boolean](https://json-schema.org/understanding-json-schema/reference/boolean "boolean (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) True when the pane touches the window’s top edge. tmux accounts for [`pane-border-status`](https://libtmux.org/en/tmux/latest/catalog/options/pane-border-status/) here, so the top row may be 1 instead of 0 when the status bar is at the top. * **[`pane_bottom`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_bottom)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Bottom edge row (inclusive), window-relative. * **[`pane_current_command`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_current_command)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Running command * **[`pane_current_path`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_current_path)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Current working directory * **[`pane_height`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_height)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Height in rows * **[`pane_id`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_id)** ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)")) Pane ID (e.g. ‘%1’) * **[`pane_index`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_index)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane index * **[`pane_left`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_left)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Left edge column, 0-based and window-relative. * **[`pane_pid`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_pid)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Process ID * **[`pane_right`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_right)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Right edge column (inclusive), window-relative. * **[`pane_title`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_title)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Pane title * **[`pane_top`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_top)**? = `null` ([integer](https://json-schema.org/understanding-json-schema/reference/numeric "numeric (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Top edge row, 0-based and window-relative. * **[`pane_tty`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_tty)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) TTY device path of the pane (e.g. ‘/dev/pts/5’). * **[`pane_width`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fpane_width)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Width in columns * **[`session_id`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fsession_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent session ID * **[`window_id`](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.output%2Fproperties%2Fwindow_id)**? = `null` ([string](https://json-schema.org/understanding-json-schema/reference/string "string (JSON Schema)") | [null](https://json-schema.org/understanding-json-schema/reference/null "null (JSON Schema)")) Parent window ID ## Annotations[#](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.annotations) * [`destructiveHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#destructiveHint) `true` * [`idempotentHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#idempotentHint) `false` * [`openWorldHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#openWorldHint) `true` * [`readOnlyHint`](https://libtmux.org/en/py/stable/mcp/reference/glossary/#readOnlyHint) `false` ## Protocol data[#](https://libtmux.org/en/py/stable/mcp/tools/respawn_pane/#mcp.tool.respawn_pane.schemas) Use the complete advertised contract for validation and client integration. Input schema ```json { "additionalProperties": false, "properties": { "environment": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "string" }, { "type": "null" } ], "default": null, "description": "Environment variables to set for the relaunched process. Each\nitem becomes one ``-e KEY=VALUE`` flag (tmux's\n``cmd-respawn-pane.c`` supports the flag repeatedly). Values\nsupplied in a mapping are redacted in the audit log on a\nper-key basis — keys like ``DATABASE_URL`` remain visible but\ntheir values are replaced by ``{len, sha256_prefix}`` digests.\nA JSON object string is redacted as one scalar digest, so its\nkeys are not retained in the audit record. Values may still\nappear briefly in the OS process table while tmux spawns the\nnew process; do not pass long-lived secrets here when a\nhost-resident agent or other tenant could observe ``ps``." }, "kill": { "default": true, "description": "When True (default), pass ``-k`` to tmux so the current\nprocess is killed before respawning. When False, respawn\nfails if the pane already has a running process.", "type": "boolean" }, "pane_id": { "description": "Pane ID (e.g. '%1'). Required.", "type": "string" }, "shell": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Replacement command for tmux to launch. When omitted, tmux\nreplays the original argv (good default for shells; may differ\nfor processes spawned via custom shell at split time). Matches\nthe ``shell`` parameter on :func:`split_window` and the\neventual upstream ``Pane.respawn(shell=)`` API." }, "socket_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "tmux socket name." }, "start_directory": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Existing directory to start in. ``~`` expands; a relative path\nresolves against the MCP server process's directory." }, "suppress_persistent_history": { "default": false, "description": "Whether to suppress persistent history for the spawned shell. Defaults\nto False for MCP and direct Python calls. This per-call option does not\ninherit LIBTMUX_SUPPRESS_HISTORY. Startup files may override these\ncontrols.", "type": "boolean" } }, "required": [ "pane_id" ], "type": "object" } ``` Output schema ```json { "description": "Serialized tmux pane.", "properties": { "is_caller": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "MCP caller identity for this pane. ``True`` when the pane matches the caller's ``TMUX_PANE`` *and* lives on the same tmux socket as the caller's ``TMUX`` (verified via socket realpath); ``False`` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; ``None`` when the MCP process is not running inside tmux at all." }, "pane_active": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Active flag ('1' or '0')" }, "pane_at_bottom": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's bottom edge." }, "pane_at_left": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's left edge." }, "pane_at_right": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's right edge." }, "pane_at_top": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True when the pane touches the window's top edge. tmux accounts for ``pane-border-status`` here, so the top row may be 1 instead of 0 when the status bar is at the top." }, "pane_bottom": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Bottom edge row (inclusive), window-relative." }, "pane_current_command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Running command" }, "pane_current_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Current working directory" }, "pane_height": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Height in rows" }, "pane_id": { "description": "Pane ID (e.g. '%1')", "type": "string" }, "pane_index": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane index" }, "pane_left": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Left edge column, 0-based and window-relative." }, "pane_pid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Process ID" }, "pane_right": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Right edge column (inclusive), window-relative." }, "pane_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pane title" }, "pane_top": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Top edge row, 0-based and window-relative." }, "pane_tty": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "TTY device path of the pane (e.g. '/dev/pts/5')." }, "pane_width": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Width in columns" }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent session ID" }, "window_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Parent window ID" } }, "required": [ "pane_id" ], "type": "object" } ```