Respawn pane

respawn_pane

respawn_pane

mutating tool

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

Returns:

PaneInfo

Use when a pane’s shell or command has wedged (hung REPL, runaway process, bad terminal mode) and you need a clean restart without destroying the pane_id references other tools or callers may still be holding. With kill=True (the default) tmux kills the current process first; optional shell relaunches with a different command; optional start_directory sets its cwd; optional environment adds per-process env vars (one -e KEY=VALUE flag per entry).

Avoid when the pane genuinely needs to go away — use kill_pane instead. Also avoid when you want to change the layout: respawn-pane preserves the pane in place.

Side effects: Kills the current process (with kill=True) and starts a new one. The pane_id is preserved — that’s the whole point of the tool. pane_pid updates to the new process.

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

Example — recover a wedged pane, relaunching the default shell:

{
  "tool": "respawn_pane",
  "arguments": {
    "pane_id": "%5"
  }
}

Example — relaunch with a different command and working directory:

{
  "tool": "respawn_pane",
  "arguments": {
    "pane_id": "%5",
    "shell": "pytest -x",
    "start_directory": "/home/user/project"
  }
}

Example — relaunch with extra environment variables:

{
  "tool": "respawn_pane",
  "arguments": {
    "pane_id": "%5",
    "shell": "pytest -x",
    "environment": {
      "PYTHONPATH": "/home/user/project/src",
      "DATABASE_URL": "postgres://localhost/test"
    }
  }
}

The audit log redacts each environment value via {len, sha256_prefix} digests but keeps the keys visible (env var names like DATABASE_URL are operator-debug-useful, while their values are the secret). Note that values may still appear briefly in the OS process table while tmux spawns the new process — see Safety tiers for details.

Response (PaneInfo):

{
  "pane_id": "%5",
  "pane_pid": "98765",
  "pane_current_command": "pytest",
  "pane_current_path": "/home/user/project",
  // ...
}

Parameters

Parameter	Type	Required	Default	Description
pane_id	str	yes	—	Pane ID (e.g. ‘%1’). Required.
kill	bool	no	True	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	no	—	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	no	—	Working directory for the relaunched command (maps to respawn-pane -c).
environment	dict[str, str]	no	—	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 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. Note that the 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	no	—	tmux socket name.