Windows¶

Inspect readonly¶

`list_windows` readonly¶

List windows in a tmux session, or all windows across sessions.

Returns: list[WindowInfo]

Use when you need window names, indices, or layout metadata within a session before selecting a window to work with.

Avoid when you need pane-level detail — use list_panes readonly.

Side effects: None. Readonly.

Example:

{
  "tool": "list_windows",
  "arguments": {
    "session_name": "dev"
  }
}

Response:

[
  {
    "window_id": "@0",
    "window_name": "editor",
    "window_index": "1",
    "session_id": "$0",
    "session_name": "dev",
    "pane_count": 2,
    "window_layout": "c195,80x24,0,0[80x12,0,0,0,80x11,0,13,1]",
    "window_active": "1",
    "window_width": "80",
    "window_height": "24"
  },
  {
    "window_id": "@1",
    "window_name": "server",
    "window_index": "2",
    "session_id": "$0",
    "session_name": "dev",
    "pane_count": 1,
    "window_layout": "b25f,80x24,0,0,2",
    "window_active": "0",
    "window_width": "80",
    "window_height": "24"
  }
]

Parameters

Parameter	Type	Required	Default	Description
`session_name`	`str`	no	—	Session name to look up. If omitted along with session_id, returns windows from all sessions.
`session_id`	`str`	no	—	Session ID (e.g. ‘$1’) to look up.
`socket_name`	`str`	no	—	tmux socket name. Defaults to LIBTMUX_SOCKET env var.
`filters`	`dict[str, str]`, `str`	no	—	Django-style filters as a dict (e.g. `{"window_name__contains": "dev"}`) or as a JSON string. Some MCP clients require the string form.

`list_panes` readonly¶

List panes in a tmux window, session, or across the entire server.

Returns: list[PaneInfo]

Use when you need to discover which panes exist in a window before sending keys or capturing output.

Side effects: None. Readonly.

Parameters

Parameter	Type	Required	Default	Description
`session_name`	`str`	no	—	Session name. If given without window params, lists all panes in the session.
`session_id`	`str`	no	—	Session ID. If given without window params, lists all panes in the session.
`window_id`	`str`	no	—	Window ID (e.g. ‘@1’). Scopes to a single window.
`window_index`	`str`	no	—	Window index within the session. Scopes to a single window.
`socket_name`	`str`	no	—	tmux socket name.
`filters`	`dict[str, str]`, `str`	no	—	Django-style filters as a dict (e.g. `{"pane_current_command__contains": "vim"}`) or as a JSON string. Some MCP clients require the string form.

Act mutating¶

`create_window` mutating¶

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.

Example:

{
  "tool": "create_window",
  "arguments": {
    "session_name": "dev",
    "window_name": "logs"
  }
}

Response:

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

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.

`split_window` mutating¶

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.

Example:

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

Response:

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

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.

`rename_window` mutating¶

Rename a tmux window.

Returns: WindowInfo

Use when a window name no longer reflects its purpose.

Side effects: Renames the window.

Parameters

Parameter	Type	Required	Default	Description
`new_name`	`str`	yes	—	The new name for the window.
`window_id`	`str`	no	—	Window ID (e.g. ‘@1’).
`window_index`	`str`	no	—	Window index within the session.
`session_name`	`str`	no	—	Session name.
`session_id`	`str`	no	—	Session ID.
`socket_name`	`str`	no	—	tmux socket name.

`select_layout` mutating¶

Set the layout of a tmux window.

Returns: WindowInfo

Use when you want to rearrange panes — even-horizontal, even-vertical, main-horizontal, main-vertical, or tiled.

Side effects: Rearranges all panes in the window.

Parameters

Parameter	Type	Required	Default	Description
`layout`	`str`	yes	—	Layout name or custom layout string. Built-in layouts: ‘even-horizontal’, ‘even-vertical’, ‘main-horizontal’, ‘main-horizontal-mirrored’, ‘main-vertical’, ‘main-vertical-mirrored’, ‘tiled’.
`window_id`	`str`	no	—	Window ID (e.g. ‘@1’).
`window_index`	`str`	no	—	Window index within the session.
`session_name`	`str`	no	—	Session name.
`session_id`	`str`	no	—	Session ID.
`socket_name`	`str`	no	—	tmux socket name.

`resize_window` mutating¶

Resize a tmux window.

Returns: WindowInfo

Use when you need to adjust the window dimensions.

Side effects: Changes window size.

Parameters

Parameter	Type	Required	Default	Description
`window_id`	`str`	no	—	Window ID (e.g. ‘@1’).
`window_index`	`str`	no	—	Window index within the session.
`session_name`	`str`	no	—	Session name.
`session_id`	`str`	no	—	Session ID.
`height`	`int`	no	—	New height in lines.
`width`	`int`	no	—	New width in columns.
`socket_name`	`str`	no	—	tmux socket name.

Destroy destructive¶

`kill_window` destructive¶

Kill (close) a tmux window. Requires exact window_id (e.g. ‘@3’).

Returns: str

Use when you’re done with a window and all its panes.

Avoid when you only want to remove one pane — use kill_pane destructive.

Side effects: Destroys the window and all its panes. Not reversible.

Parameters

Parameter	Type	Required	Default	Description
`window_id`	`str`	yes	—	Window ID (e.g. ‘@1’). Required — no fallback resolution.
`socket_name`	`str`	no	—	tmux socket name.

Windows¶

Inspect readonly¶

list_windows readonly¶

list_panes readonly¶

Act mutating¶

create_window mutating¶

split_window mutating¶

rename_window mutating¶

select_layout mutating¶

resize_window mutating¶

Destroy destructive¶

kill_window destructive¶

`list_windows` readonly¶

`list_panes` readonly¶

`create_window` mutating¶

`split_window` mutating¶

`rename_window` mutating¶

`select_layout` mutating¶

`resize_window` mutating¶

`kill_window` destructive¶