# respawn_pane

Source: https://libtmux.org/en/py/latest/mcp/tools/respawn_pane/

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

MCP is in development

Server behavior and tool contracts may change. Tool availability depends on the server configuration.

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/latest/mcp/tools/kill_pane/) + [split\_window](https://libtmux.org/en/py/latest/mcp/tools/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`](https://libtmux.org/en/py/latest/mcp/tools/list_panes/) first.

Tip: call [`get_pane_info`](https://libtmux.org/en/py/latest/mcp/tools/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).

[All Python tools](../) · [JSON](../respawn_pane.json) · [Source](https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/__init__.py#L121)

## Arguments

* `environment` 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 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\`\`.

  Default: `null`.

* `kill` optional · boolean

  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.

  Default: `true`.

* `pane_id` required · string

  Pane ID (e.g. '%1'). Required.

* `shell` 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 :func:\`split\_window\` and the eventual upstream \`\`Pane.respawn(shell=)\`\` API.

  Default: `null`.

* `socket_name` optional

  tmux socket name.

  Default: `null`.

* `start_directory` optional

  Existing directory to start in. \`\`\~\`\` expands; a relative path resolves against the MCP server process's directory.

  Default: `null`.

* `suppress_persistent_history` optional · boolean

  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.

  Default: `false`.

## Schemas

The schema defines required fields, nested values, defaults, and validation constraints.