Create window¶

`create_window`¶

create_window

Create a new window in a tmux session.

Returns:: WindowInfo

Use when you need a new terminal workspace within an existing session.

Side effects: Creates a new window. Attaches to it if attach is true.

environment accepts a mapping or JSON object string and applies only to the process started in the new window; 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 create_window copies and merges best-effort no-disk history controls for only the spawned process. It does not change the tmux session environment, so future windows and 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. 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": "create_window",
  "arguments": {
    "session_name": "dev",
    "window_name": "logs"
  }
}

Example — launch a test window with scoped settings:

{
  "tool": "create_window",
  "arguments": {
    "session_name": "dev",
    "window_name": "tests",
    "environment": {
      "PYTHONPATH": "src"
    },
    "suppress_persistent_history": true
  }
}

Response (WindowInfo):

{
  "window_id": "@2",
  "window_name": "logs",
  "window_index": "3",
  "session_id": "$0",
  "session_name": "dev",
  "pane_count": 1,
  "window_layout": "b25f,80x24,0,0,5",
  "window_active": "1",
  "window_width": "80",
  "window_height": "24",
  "active_pane_id": "%5"
}

Parameters

Parameter	Type	Required	Default	Description
`session_name`	str	no	—	Session name to look up.
`session_id`	str	no	—	Session ID (e.g. ‘$1’) to look up.
`window_name`	str	no	—	Name for the new window.
`start_directory`	str	no	—	Working directory for the new window.
`attach`	bool	no	`False`	Whether to make the new window active.
`direction`	`enum`	no	—	Window placement direction. One of: `'before'`, `'after'`.
`socket_name`	str	no	—	tmux socket name. Defaults to LIBTMUX_SOCKET env var.
`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.

Create window¶

create_window¶

`create_window`¶