Wait for a window's panes concurrently to speed up loads

CHANGES

@@ -44,6 +44,24 @@ $ tmuxp@next load yoursession
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### Breaking changes
+
+#### `before_script` output now goes to the terminal by default (#1056)
+
+A workspace's `before_script` now runs attached to your terminal, so interactive prompts and TTY-aware tools behave normally. Previously its output was captured into the load progress panel (up to three lines) by default. To restore panel capture, pass `--progress-lines` (or set `TMUXP_PROGRESS_LINES`):
+
+```console
+$ tmuxp load --progress-lines 3 myworkspace
+```
+
+### What's new
+
+#### Faster workspace loads (#1056)
+
+Loading a workspace is faster: {ref}`tmuxp-load` now prepares panes in a window together when config-order dependencies allow it, rather than waiting on every pane one at a time. Workspaces with multiple panes per window — particularly with a slow interactive shell startup — open noticeably quicker, with no changes to your configuration.
+
+See {ref}`loading-workspaces` for an overview of how a load proceeds.
+
 ## tmuxp 1.71.0 (2026-06-27)
 
 tmuxp 1.71.0 bumps libtmux to 0.59.0, adding support for tmux 3.7.

docs/cli/load.md

@@ -157,13 +157,16 @@ $ tmuxp --log-level [LEVEL] load [filename] --log-file [log_filename]
 
 When loading a workspace, tmuxp shows an animated spinner with build progress. The spinner updates as windows and panes are created, giving real-time feedback during session builds.
 
+See {ref}`loading-workspaces` for how tmuxp creates windows and panes during
+load and how to read the default progress line.
+
 ### Presets
 
 Five built-in presets control the spinner format:
 
 | Preset | Format |
 |--------|--------|
-| `default` | `Loading workspace: {session} {bar} {progress} {window}` |
+| `default` | `Loading workspace: {session} {bar} {build_progress} {window}` |
 | `minimal` | `Loading workspace: {session} [{window_progress}]` |
 | `window` | `Loading workspace: {session} {window_bar} {window_progress_rel}` |
 | `pane` | `Loading workspace: {session} {pane_bar} {session_pane_progress}` |
@@ -191,17 +194,20 @@ Use a custom format string with any of the available tokens:
 | `{window}` | Current window name |
 | `{window_index}` | Current window number (1-based) |
 | `{window_total}` | Total number of windows |
+| `{windows_created}` | Number of windows created so far |
 | `{window_progress}` | Window fraction (e.g. `1/3`) |
+| `{window_progress_created}` | Created windows fraction (e.g. `2/3`) |
 | `{window_progress_rel}` | Completed windows fraction (e.g. `1/3`) |
 | `{windows_done}` | Number of completed windows |
 | `{windows_remaining}` | Number of remaining windows |
 | `{pane_index}` | Current pane number in the window |
 | `{pane_total}` | Total panes in the current window |
 | `{pane_progress}` | Pane fraction (e.g. `2/4`) |
 | `{progress}` | Combined progress (e.g. `1/3 win · 2/4 pane`) |
+| `{build_progress}` | Finished windows over created windows (e.g. `1/3 win · pane 2/4`) |
 | `{session_pane_progress}` | Panes completed across the session (e.g. `5/10`) |
 | `{overall_percent}` | Pane-based completion percentage (0–100) |
-| `{bar}` | Composite progress bar |
+| `{bar}` | Build progress bar: finished, created, and empty window segments |
 | `{pane_bar}` | Pane-based progress bar |
 | `{window_bar}` | Window-based progress bar |
 | `{status_icon}` | Status icon (⏸ during before_script) |
@@ -214,21 +220,21 @@ $ tmuxp load --progress-format "{session} {bar} {overall_percent}%" myproject
 
 ### Panel lines
 
-The spinner shows script output in a panel below the spinner line. Control the panel height with `--progress-lines`:
+By default, `before_script` runs with its normal terminal output before the spinner appears. Use `--progress-lines` to capture that output in a panel below the spinner line:
 
-Hide the panel entirely (script output goes to stdout):
+Keep native script output and hide the panel:
 
 ```console
 $ tmuxp load --progress-lines 0 myproject
 ```
 
-Show unlimited lines (capped to terminal height):
+Capture unlimited lines (capped to terminal height):
 
 ```console
 $ tmuxp load --progress-lines -1 myproject
 ```
 
-Set a custom height (default is 3):
+Capture five lines:
 
 ```console
 $ tmuxp load --progress-lines 5 myproject

docs/configuration/environmental-variables.md

@@ -60,15 +60,15 @@ Equivalent to the `--progress-format` CLI flag.
 
 ## `TMUXP_PROGRESS_LINES`
 
-Number of script-output lines shown in the spinner panel. Defaults to `3`.
+Capture `before_script` output in the spinner panel with this many lines. By default, scripts keep their normal terminal output.
 
-Set to `0` to hide the panel entirely (script output goes to stdout):
+Set to `0` to keep native script output and hide the panel:
 
 ```console
 $ TMUXP_PROGRESS_LINES=0 tmuxp load myproject
 ```
 
-Set to `-1` for unlimited lines (capped to terminal height):
+Set to `-1` to capture unlimited lines (capped to terminal height):
 
 ```console
 $ TMUXP_PROGRESS_LINES=-1 tmuxp load myproject

docs/topics/index.md

@@ -7,6 +7,12 @@ Conceptual guides and workflow documentation.
 ::::{grid} 1 1 2 2
 :gutter: 2 2 3 3
 
+:::{grid-item-card} Loading workspaces
+:link: loading-workspaces
+:link-type: doc
+How tmuxp creates windows, panes, and progress output.
+:::
+
 :::{grid-item-card} Workflows
 :link: workflows
 :link-type: doc
@@ -46,6 +52,7 @@ instead of raw shell commands, supports JSON and YAML, and can
 :hidden:
 
 workflows
+loading-workspaces
 plugins
 library-vs-cli
 troubleshooting

docs/topics/loading-workspaces.md

@@ -0,0 +1,58 @@
+(loading-workspaces)=
+
+# Loading workspaces
+
+When you run `tmuxp load`, tmuxp creates the tmux session described by your
+workspace file, waits for panes to be ready, then finishes each window by
+applying layouts and sending commands.
+
+## What happens during load
+
+tmuxp builds each window in config order.
+
+For each window, tmuxp creates the window and prepares its panes. When later
+pane `start_directory` values already exist, panes can start their shells
+together and tmuxp waits for them together.
+
+Once the panes are ready, tmuxp applies layout, sends configured commands,
+runs window-level configuration, and fires
+{meth}`~tmuxp.plugin.TmuxpPlugin.after_window_finished` plugin hooks.
+
+This means {meth}`~tmuxp.plugin.TmuxpPlugin.on_window_create` runs while the
+window is created, while
+{meth}`~tmuxp.plugin.TmuxpPlugin.after_window_finished` runs later, after that
+window has been laid out and configured.
+
+## Reading the progress line
+
+The default progress line reports the same build in a compact form:
+
+```text
+Loading workspace: study ▓░░░░░░░░░ 0/1 win · pane 3/4 learning-asyncio
+```
+
+The fraction before `win` is finished windows over windows created so far. In
+the example above, one window has been created and has not finished yet.
+
+The `pane` fraction describes the current window's pane creation progress. When
+a new window starts, this can briefly show `pane 0/N` before tmuxp creates the
+first pane for that window.
+
+The progress bar shows the whole workspace:
+
+- `█` means a window is finished.
+- `▓` means a window has been created but is not finished yet.
+- `░` means a window has not been created yet.
+
+Once tmuxp enters the finish phase, the finished-window count rises:
+
+```text
+Loading workspace: study █░░░░░░░░░ 1/1 win learning-asyncio
+```
+
+## Why tmuxp loads this way
+
+Preparing a window's panes before layout lets shell startup happen in parallel
+when config-order dependencies allow it. Layout and commands then run after the
+panes are ready, which avoids resizing panes while shells are still drawing
+their first prompts.