# libtmux_mcp.tools.pane_tools.respawn_pane

- **Module:** libtmux_mcp.tools.pane_tools
- **Package:** libtmux-mcp
- **Language:** Python
- **Kind:** function
- **Source:** https://github.com/tmux-python/libtmux-mcp/blob/4daddc0dfca96c43bf521d818bf91564e1434760/src/libtmux_mcp/tools/pane_tools/lifecycle.py#L70
- **Page:** https://libtmux.org/en/py/latest/mcp/reference/libtmux_mcp-tools-pane_tools-respawn_pane/

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

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 :func:`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.