List windows

list_windows

list_windows

readonly tool

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.

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.