Split window¶

`split_window`¶

split_window

Split a tmux window to create a new pane.

Returns:: PaneInfo

Use when you need side-by-side or stacked terminals within the same window.

Side effects: Creates a new pane by splitting an existing one.

environment accepts a mapping or JSON object string and applies only to the process started in the new pane; it does not change the tmux session environment. Values can remain visible in the tmux client argv and child environment even though the MCP audit record is redacted. Pass credential references, not literal credentials; see Safety tiers.

suppress_persistent_history defaults to false for MCP and direct Python calls. It does not inherit LIBTMUX_SUPPRESS_HISTORY. Leave it false to add no history controls for this call. That choice cannot remove inherited, session, or startup-file controls.

Set it to true and split_window copies and merges best-effort no-disk history controls for only the spawned process. It does not change the tmux session environment, so later panes do not receive the controls from this call. The shell can retain in-memory history, and a startup file can override these controls after the process starts.

When you enable it, tmux environment arguments are added, but the spawned process command text is not prefixed or rewritten. The shell text is passed through unchanged. If you also pass environment, any history-control values must agree with the policy. A conflict fails the call, names the variable without including the conflicting value, and is never retried without suppression. See History suppression for shell behavior and Safety tiers for output, scrollback, process, transcript, hook, and logging boundaries.

Example:

{
  "tool": "split_window",
  "arguments": {
    "session_name": "dev",
    "direction": "right"
  }
}

Example — split off a test pane with scoped settings:

{
  "tool": "split_window",
  "arguments": {
    "session_name": "dev",
    "direction": "right",
    "environment": {
      "APP_ENV": "test"
    },
    "suppress_persistent_history": true
  }
}

Response (PaneInfo):

{
  "pane_id": "%4",
  "pane_index": "1",
  "pane_width": "39",
  "pane_height": "24",
  "pane_current_command": "zsh",
  "pane_current_path": "/home/user/myproject",
  "pane_pid": "3732",
  "pane_title": "",
  "pane_active": "0",
  "window_id": "@0",
  "session_id": "$0",
  "is_caller": false
}

Parameters

Parameter	Type	Required	Default	Description
`pane_id`	str	no	—	Pane ID to split from. If given, splits adjacent to this pane.
`session_name`	str	no	—	Session name.
`session_id`	str	no	—	Session ID (e.g. ‘$1’).
`window_id`	str	no	—	Window ID (e.g. ‘@1’).
`window_index`	str	no	—	Window index within the session.
`direction`	`enum`	no	—	Split direction. One of: `'above'`, `'below'`, `'left'`, `'right'`.
`size`	str \| int	no	—	Size of the new pane. Use a string with ‘%%’ suffix for percentage (e.g. ‘50%%’) or an integer for lines/columns.
`start_directory`	str	no	—	Working directory for the new pane.
`shell`	str	no	—	Shell command to run in the new pane.
`socket_name`	str	no	—	tmux socket name.
`environment`	dict[str, str] \| str	no	—	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.
`suppress_persistent_history`	bool	no	`False`	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.

Split window¶

split_window¶

`split_window`¶