Workspace builder roadmap: classic default, pluggable builders, readiness policy, and parallel loading

Summary

Workspace loading performance work has exposed several concerns that should be separated instead of solved in one builder implementation.

Related context:

• #1053 reports slow workspace loads.
• #1056 experiments with faster per-window pane readiness.
• #1054 explores an experimental chain-based builder.
• #1049 is part of the broader workspace parity work that makes builder behavior and imported workspace semantics more important.

This issue is an umbrella for a staged workspace-builder roadmap. The first step should keep the classic behavior as the default and make builder selection explicit. Later steps can add a formal builder interface, readiness-policy configuration, and a parallel builder without risking compatibility for existing workspace files.

Proposed stages

1. Classic builder base PR

Keep the existing WorkspaceBuilder behavior as the default and make that default explicit as the classic builder.

The base PR should:

• Treat the current builder as the classic builder.
• Keep classic behavior as the default.
• Add a workspace config parameter that selects a builder by Python dotted path.
• Route tmuxp load through that builder selection.
• Preserve existing workspace behavior unless a different builder is explicitly configured.
• Avoid changing pane-readiness behavior or parallelizing behavior in the same PR.

Example shape:

workspace_builder: tmuxp.workspace.builder.WorkspaceBuilder

The exact key name can be refined in the PR, but the behavior should be clear: users can point tmuxp at a builder class by Python dotted path.

2. Builder protocol and entry points

Create a follow-up issue and PR for a formal workspace-builder interface.

That work should define what a custom builder must provide, including constructor expectations, .build(), .session, progress callbacks, script-output callbacks, plugin lifecycle compatibility, and append/detached behavior.

It should also consider package entry points so builders can be distributed outside tmuxp without requiring users to reference internal module paths directly.

The interface should allow both sync and future async builders, even if tmuxp only executes sync builders initially.

3. Pane-readiness configuration

Create a follow-up issue and PR for configuring pane-readiness behavior separately from builder selection.

This should allow users to choose whether tmuxp waits for pane prompts before layout and command dispatch. The default should preserve today’s safe behavior unless there is a deliberate compatibility decision.

Possible policy shape:

pane_readiness: auto

Potential values:

• auto: enable readiness waiting when it is needed for known shell behavior, especially zsh prompt redraw safety.
• always: always wait for default-shell panes before layout and command dispatch.
• never: skip readiness waiting for users who prefer speed and accept prompt/layout race risk.

This should remain useful even before a parallel builder exists.

4. Parallel builder

Create a follow-up issue and PR for a parallel builder that is explicitly opt-in.

That builder can prioritize faster pane creation and concurrent readiness observation, while the classic builder remains available for configurations that depend on strict pane-by-pane side effects.

The parallel builder should document that pane commands are not guaranteed to prepare later pane split-time inputs such as start_directory, shell, window_shell, or pane environment. Users who need those dependencies can keep the classic builder or move setup into before_script / shell_command_before.

5. Developer documentation

Add developer docs for workspace builder classes.

The docs should explain:

• How tmuxp loads a workspace and hands it to a builder.
• How custom builders can use libtmux object APIs and raw tmux commands.
• Which builder hooks and callbacks must be honored.
• How to test a custom builder.
• How to configure a custom builder by dotted path or entry point.
• When to use classic behavior versus experimental or parallel behavior.

Docs should include small examples and test guidance so external builders are realistic, not just theoretically supported.

Goals

• Preserve compatibility by keeping the classic builder as the default.
• Avoid hiding behavior changes behind heuristics.
• Let performance work continue through explicit opt-in builders.
• Give advanced users a supported way to customize builder behavior.
• Keep pane-readiness policy independent from builder architecture.

Non-goals

• Do not merge the parallel behavior into the default builder as part of the base PR.
• Do not require the chain builder experiment to be production-ready before defining the classic-builder selection path.
• Do not make async execution required in the first interface PR.
• Do not remove existing plugin lifecycle hooks or progress callbacks.

Acceptance criteria

• A base PR exists that keeps classic behavior as the default and supports selecting a builder class by Python dotted path.
• Follow-up issues exist for the builder protocol / entry points, pane-readiness configuration, parallel builder, and developer documentation.
• Public docs explain the classic builder default and how custom builders can be configured.
• Existing workspace files continue to load with classic behavior unless they opt into a different builder.

Start by tracing the existing WorkspaceBuilder and the tmuxp load entry point to understand how workspace configuration currently selects and invokes a builder. The initial work is complete when classic behavior remains the default, an explicitly configured Python dotted path can select another builder, existing workspace files still load unchanged, and follow-up issues cover the later roadmap stages.