mcp(feat[split_window_many]): Fan panes out and keep the layout

why: Splitting halves a pane, so six split_window calls in a small
window stop at "no space for new pane". libtmux's Window.split_many
re-applies the layout after each split.

what:
- Add split_window_many (count 1 to 64, layout, start_directory, shell,
  environment) returning the new panes in order
- Document it, list it in the index, README and tool expectations
- Tests: six panes in an 80x24 window, bad count and layout; the first
  fails when the call is replaced by plain splits

Author: tony

CHANGES

@@ -17,6 +17,12 @@ marker to be read. A process still running at the timeout comes back with
 `timed_out=true`. The pane stays on screen, dead, so `capture_pane` can read its
 output.
 
+**`split_window_many` adds several panes and keeps the layout**
+
+`split_window_many` adds `count` panes (1 to 64) to a window and re-applies a
+layout after each split, so a fan-out of workers no longer stops at "no space
+for new pane" in a small window.
+
 **`create_session` can reuse a session and set its scrollback**
 
 `create_session(session_name=..., if_exists="reuse")` returns the session of

README.md

@@ -34,7 +34,7 @@ commands, read output, orchestrate panes.
 | **Server** | `list_servers`, `list_sessions`, `create_session`, `kill_server`, `get_server_info` |
 | **Batch** | `call_read_tools_batch` |
 | **Session** | `list_windows`, `get_session_info`, `create_window`, `rename_session`, `select_window`, `kill_session` |
-| **Window** | `list_panes`, `get_window_info`, `split_window`, `rename_window`, `select_layout`, `resize_window`, `move_window`, `kill_window` |
+| **Window** | `list_panes`, `get_window_info`, `split_window`, `split_window_many`, `rename_window`, `select_layout`, `resize_window`, `move_window`, `kill_window` |
 | **Pane** | `run_command`, `send_keys`, `send_keys_batch`, `paste_text`, `capture_pane`, `capture_since`, `snapshot_pane`, `search_panes`, `find_pane_by_position`, `get_pane_info`, `wait_for_text`, `wait_for_channel`, `wait_for_pane_exit`, `signal_channel`, `display_message`, `select_pane`, `swap_pane`, `resize_pane`, `set_pane_title`, `clear_pane`, `pipe_pane`, `enter_copy_mode`, `exit_copy_mode`, `respawn_pane`, `kill_pane` |
 | **Options** | `show_option`, `set_option` |
 | **Environment** | `show_environment`, `set_environment` |

docs/tools/index.md

@@ -36,6 +36,7 @@ leave socket selection inside each nested tool's arguments. See
 - New session → {tool}`create-session`
 - New window → {tool}`create-window`
 - New pane → {tool}`split-window`
+- Several panes at once (one per worker) → {tool}`split-window-many`
 
 **Navigating?**
 - Switch pane → {tool}`select-pane` (by ID or direction)
@@ -352,6 +353,12 @@ Add a window to a session.
 Split a window into panes.
 :::
 
+:::{grid-item-card} split_window_many
+:link: split-window-many
+:link-type: ref
+Add several panes at once, keeping a layout applied.
+:::
+
 :::{grid-item-card} send_keys
 :link: send-keys
 :link-type: ref

docs/tools/window/index.md

@@ -17,6 +17,10 @@ Read metadata for one window.
 Split a window into a new pane.
 :::
 
+:::{grid-item-card} {tooliconl}`split-window-many`
+Add several panes at once, keeping a layout applied.
+:::
+
 :::{grid-item-card} {tooliconl}`rename-window`
 Rename an existing window.
 :::
@@ -46,6 +50,7 @@ Terminate a window. Not reversible.
 list-panes
 get-window-info
 split-window
+split-window-many
 rename-window
 select-layout
 resize-window

docs/tools/window/split-window-many.md

@@ -0,0 +1,30 @@
+# Split window many
+
+Adds several panes to a window in one call and keeps a layout applied after
+every split. Splitting halves a pane, so a window runs out of room after a few
+{tooliconl}`split-window` calls with "no space for new pane"; applying a layout
+once at the end does not help, because the failure comes first.
+
+```python
+panes = split_window_many(window_id="@1", count=6, layout="tiled")
+```
+
+```{fastmcp-tool} window_tools.split_window_many
+```
+
+**Use when** you want one pane per worker, per host or per log.
+
+**Avoid when** you need a specific split direction or size for one pane. Use
+{tooliconl}`split-window`.
+
+**Side effects:** Creates `count` panes and changes the window's layout. The
+window keeps the layout afterwards. When the window is too small for another
+pane even after the layout is applied, the call fails and the panes created so
+far remain.
+
+`environment`, `start_directory` and `suppress_persistent_history` apply to
+every new pane exactly as for {tooliconl}`split-window`; see {ref}`trust` for
+what environment values expose.
+
+```{fastmcp-tool-input} window_tools.split_window_many
+```

src/libtmux_mcp/tools/window_tools.py

@@ -256,6 +256,100 @@ def split_window(
     return _serialize_pane(new_pane)
 
 
+#: Most panes one ``split_window_many`` call adds. A window that cannot hold
+#: them fails at tmux's own limit; this stops a typo from asking for thousands.
+_SPLIT_MANY_MAX_COUNT = 64
+
+
+@handle_tool_errors
+def split_window_many(
+    count: int,
+    session_name: str | None = None,
+    session_id: str | None = None,
+    window_id: str | None = None,
+    window_index: str | None = None,
+    layout: str = "tiled",
+    start_directory: str | None = None,
+    shell: str | None = None,
+    socket_name: str | None = None,
+    *,
+    environment: dict[str, str] | str | None = None,
+    suppress_persistent_history: bool = False,
+) -> list[PaneInfo]:
+    """Add ``count`` panes to a window, keeping a layout applied throughout.
+
+    Use to fan work out across several panes at once, for example one
+    worker per pane. Splitting halves a pane, so a window runs out of room
+    after a few ``split_window`` calls with "no space for new pane"; this
+    re-applies ``layout`` after every split so the window keeps room.
+    Returns the new panes in creation order.
+
+    Parameters
+    ----------
+    count : int
+        Number of panes to add, 1 to 64.
+    session_name : str, optional
+        Session name.
+    session_id : str, optional
+        Session ID (e.g. '$1').
+    window_id : str, optional
+        Window ID (e.g. '@1').
+    window_index : str, optional
+        Window index within the session.
+    layout : str
+        Layout kept applied: ``tiled`` (default), ``even-horizontal``,
+        ``even-vertical``, ``main-horizontal`` or ``main-vertical``.
+    start_directory : str, optional
+        Existing directory to start every new pane in. ``~`` expands; a
+        relative path resolves against the MCP server process's directory.
+    shell : str, optional
+        Shell command to run in every new pane.
+    socket_name : str, optional
+        tmux socket name.
+    environment : dict or str, optional
+        Per-process environment for every new pane, as a mapping or JSON
+        object string. 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
+        Whether to suppress persistent history for the spawned shells.
+        Defaults to False. This per-call option does not inherit
+        LIBTMUX_SUPPRESS_HISTORY.
+
+    Returns
+    -------
+    list[PaneInfo]
+        The new panes, in creation order.
+    """
+    if not 1 <= count <= _SPLIT_MANY_MAX_COUNT:
+        msg = f"count must be between 1 and {_SPLIT_MANY_MAX_COUNT} (received {count})"
+        raise ExpectedToolError(msg)
+    spawn_environment = _prepare_spawn_environment(
+        environment,
+        suppress_persistent_history=suppress_persistent_history,
+    )
+    server = _get_server(socket_name=socket_name)
+    window = _resolve_window(
+        server,
+        window_id=window_id,
+        window_index=window_index,
+        session_name=session_name,
+        session_id=session_id,
+    )
+    try:
+        panes = window.split_many(
+            count,
+            layout=layout,
+            start_directory=_prepare_start_directory(start_directory),
+            shell=shell,
+            environment=spawn_environment,
+        )
+    except ValueError as e:
+        raise ExpectedToolError(str(e)) from e
+    return [_serialize_pane(pane) for pane in panes]
+
+
 @handle_tool_errors
 def rename_window(
     new_name: str,
@@ -514,6 +608,11 @@ def register(mcp: FastMCP) -> None:
         annotations=ANNOTATIONS_AMBIENT_UNKNOWN,
         tags={TOOLSET_EXECUTE},
     )(split_window)
+    mcp.tool(
+        title="Split tmux Window Many",
+        annotations=ANNOTATIONS_AMBIENT_UNKNOWN,
+        tags={TOOLSET_EXECUTE},
+    )(split_window_many)
     mcp.tool(
         title="Rename tmux Window",
         annotations=ANNOTATIONS_AMBIENT_UNKNOWN,

tests/test_server.py

@@ -806,10 +806,11 @@ def test_probe_hint_visible_only_on_an_inspect_only_surface(
         "rename_session",
         "kill_session",
         "select_window",
-        # 8 window-level
+        # 9 window-level
         "list_panes",
         "get_window_info",
         "split_window",
+        "split_window_many",
         "rename_window",
         "kill_window",
         "select_layout",

tests/test_tool_annotations.py

@@ -84,6 +84,7 @@
             "set_environment",
             "set_option",
             "split_window",
+            "split_window_many",
         }
     ),
     TOOLSET_TEARDOWN: frozenset(

tests/test_window_tools.py

@@ -18,6 +18,7 @@
     resize_window,
     select_layout,
     split_window,
+    split_window_many,
 )
 
 if t.TYPE_CHECKING:
@@ -381,3 +382,43 @@ def test_kill_window(mcp_server: Server, mcp_session: Session) -> None:
         socket_name=mcp_server.socket_name,
     )
     assert "killed" in result.lower()
+
+
+def test_split_window_many_adds_panes_in_a_small_window(
+    mcp_server: Server, mcp_session: Session
+) -> None:
+    """Six splits fit in a window that rejects them without a layout in between."""
+    window = mcp_session.active_window
+    window.resize(height=24, width=80)
+
+    result = split_window_many(
+        count=6,
+        window_id=window.window_id,
+        socket_name=mcp_server.socket_name,
+    )
+
+    assert len(result) == 6
+    assert len({pane.pane_id for pane in result}) == 6
+    window.refresh()
+    assert len(window.panes) == 7
+    assert window.window_layout is not None
+
+
+def test_split_window_many_refuses_bad_count_and_layout(
+    mcp_server: Server, mcp_session: Session
+) -> None:
+    """A count out of range and an unknown layout are agent-correctable errors."""
+    from fastmcp.exceptions import ToolError
+
+    window_id = mcp_session.active_window.window_id
+    with pytest.raises(ToolError, match="count must be between"):
+        split_window_many(
+            count=0, window_id=window_id, socket_name=mcp_server.socket_name
+        )
+    with pytest.raises(ToolError):
+        split_window_many(
+            count=2,
+            window_id=window_id,
+            layout="not-a-layout",
+            socket_name=mcp_server.socket_name,
+        )