Python MCP reference

tool MCPstable

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

MCP request method: tools/call Send respawn_pane as the tool name, with the arguments below.

Arguments#

environment? = null (Record<string, string> | string | null) #

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? = true (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.
pane_id (string) #

Pane ID (e.g. ‘%1’). Required.
shell? = null (string | null) #

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.
socket_name? = null (string | null) #

tmux socket name.
start_directory? = null (string | null) #

Existing directory to start in. ~ expands; a relative path resolves against the MCP server process’s directory.
suppress_persistent_history? = false (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.

No other arguments are accepted.

Result#

Returns object

is_caller? = null (boolean | null) #

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? = null (string | null) #

Active flag (‘1’ or ‘0’)
pane_at_bottom? = null (boolean | null) #

True when the pane touches the window’s bottom edge.
pane_at_left? = null (boolean | null) #

True when the pane touches the window’s left edge.
pane_at_right? = null (boolean | null) #

True when the pane touches the window’s right edge.
pane_at_top? = null (boolean | null) #

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? = null (integer | null) #

Bottom edge row (inclusive), window-relative.
pane_current_command? = null (string | null) #

Running command
pane_current_path? = null (string | null) #

Current working directory
pane_height? = null (string | null) #

Height in rows
pane_id (string) #

Pane ID (e.g. ‘%1’)
pane_index? = null (string | null) #

Pane index
pane_left? = null (integer | null) #

Left edge column, 0-based and window-relative.
pane_pid? = null (string | null) #

Process ID
pane_right? = null (integer | null) #

Right edge column (inclusive), window-relative.
pane_title? = null (string | null) #

Pane title
pane_top? = null (integer | null) #

Top edge row, 0-based and window-relative.
pane_tty? = null (string | null) #

TTY device path of the pane (e.g. ‘/dev/pts/5’).
pane_width? = null (string | null) #

Width in columns
session_id? = null (string | null) #

Parent session ID
window_id? = null (string | null) #

Parent window ID

Annotations#

destructiveHint: true
idempotentHint: false
openWorldHint: true
readOnlyHint: false

Protocol data#

Use the complete advertised contract for validation and client integration.

Input schema

{
  "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

{
  "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"
}

Scripting & web

Compiled & native

JVM

.NET

tmux

`respawn_pane`

Arguments#

Result#

Annotations#

Protocol data#