Python MCP reference

tool MCPstable

`split_window`

Split a tmux window to create a new pane.

Creates a new pane by splitting an existing one. Use direction to choose above/below/left/right. Returns the new pane’s info including its pane_id.

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

Arguments#

direction? = null ("above" | "below" | "left" | "right" | null) #

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

Per-process environment as a mapping or JSON object string. Values do not modify the tmux session environment. Each item becomes a tmux -e launch option. Values may be visible to host process inspection in the tmux client argv during launch and in the child environment afterward; MCP audit redaction does not hide either surface. Pass credential references, not literal credentials.
pane_id? = null (string | null) #

Pane ID to split from. If given, splits adjacent to this pane.
session_id? = null (string | null) #

Session ID (e.g. ‘$1’).
session_name? = null (string | null) #

Session name.
shell? = null (string | null) #

Shell command to run in the new pane.
size? = null (string | integer | null) #

Size of the new pane. Use a string with ’%%’ suffix for percentage (e.g. ‘50%%’) or an integer for lines/columns.
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.
window_id? = null (string | null) #

Window ID (e.g. ‘@1’).
window_index? = null (string | null) #

Window index within the session.

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": {
    "direction": {
      "anyOf": [
        {
          "enum": [
            "above",
            "below",
            "left",
            "right"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Split direction."
    },
    "environment": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Per-process environment as a mapping or JSON object string. Values do\nnot modify the tmux session environment. Each item becomes a tmux\n``-e`` launch option. Values may be visible to host process inspection\nin the tmux client argv during launch and in the child environment\nafterward; MCP audit redaction does not hide either surface. Pass\ncredential references, not literal credentials."
    },
    "pane_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Pane ID to split from. If given, splits adjacent to this pane."
    },
    "session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Session ID (e.g. '$1')."
    },
    "session_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Session name."
    },
    "shell": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Shell command to run in the new pane."
    },
    "size": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Size of the new pane. Use a string with '%%' suffix for\npercentage (e.g. '50%%') or an integer for lines/columns."
    },
    "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"
    },
    "window_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Window ID (e.g. '@1')."
    },
    "window_index": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Window index within the session."
    }
  },
  "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

`split_window`

Arguments#

Result#

Annotations#

Protocol data#