Title: Workspace builder roadmap: classic default, pluggable builders, readiness policy, and parallel loading · Issue #1058 · tmux-python/tmuxp · GitHub
Open Graph Title: Workspace builder roadmap: classic default, pluggable builders, readiness policy, and parallel loading · Issue #1058 · tmux-python/tmuxp
X Title: Workspace builder roadmap: classic default, pluggable builders, readiness policy, and parallel loading · Issue #1058 · tmux-python/tmuxp
Description: 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-wind...
Open Graph Description: 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...
X Description: 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...
Opengraph URL: https://github.com/tmux-python/tmuxp/issues/1058
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Workspace builder roadmap: classic default, pluggable builders, readiness policy, and parallel loading","articleBody":"## Summary\n\nWorkspace loading performance work has exposed several concerns that should be separated instead of solved in one builder implementation.\n\nRelated context:\n\n- #1053 reports slow workspace loads.\n- #1056 experiments with faster per-window pane readiness.\n- #1054 explores an experimental chain-based builder.\n- #1049 is part of the broader workspace parity work that makes builder behavior and imported workspace semantics more important.\n\nThis 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.\n\n## Proposed stages\n\n### 1. Classic builder base PR\n\nKeep the existing `WorkspaceBuilder` behavior as the default and make that default explicit as the classic builder.\n\nThe base PR should:\n\n- Treat the current builder as the classic builder.\n- Keep classic behavior as the default.\n- Add a workspace config parameter that selects a builder by Python dotted path.\n- Route `tmuxp load` through that builder selection.\n- Preserve existing workspace behavior unless a different builder is explicitly configured.\n- Avoid changing pane-readiness behavior or parallelizing behavior in the same PR.\n\nExample shape:\n\n```yaml\nworkspace_builder: tmuxp.workspace.builder.WorkspaceBuilder\n```\n\nThe 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.\n\n### 2. Builder protocol and entry points\n\nCreate a follow-up issue and PR for a formal workspace-builder interface.\n\nThat 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.\n\nIt should also consider package entry points so builders can be distributed outside tmuxp without requiring users to reference internal module paths directly.\n\nThe interface should allow both sync and future async builders, even if tmuxp only executes sync builders initially.\n\n### 3. Pane-readiness configuration\n\nCreate a follow-up issue and PR for configuring pane-readiness behavior separately from builder selection.\n\nThis 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.\n\nPossible policy shape:\n\n```yaml\npane_readiness: auto\n```\n\nPotential values:\n\n- `auto`: enable readiness waiting when it is needed for known shell behavior, especially zsh prompt redraw safety.\n- `always`: always wait for default-shell panes before layout and command dispatch.\n- `never`: skip readiness waiting for users who prefer speed and accept prompt/layout race risk.\n\nThis should remain useful even before a parallel builder exists.\n\n### 4. Parallel builder\n\nCreate a follow-up issue and PR for a parallel builder that is explicitly opt-in.\n\nThat 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.\n\nThe 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`.\n\n### 5. Developer documentation\n\nAdd developer docs for workspace builder classes.\n\nThe docs should explain:\n\n- How tmuxp loads a workspace and hands it to a builder.\n- How custom builders can use libtmux object APIs and raw tmux commands.\n- Which builder hooks and callbacks must be honored.\n- How to test a custom builder.\n- How to configure a custom builder by dotted path or entry point.\n- When to use classic behavior versus experimental or parallel behavior.\n\nDocs should include small examples and test guidance so external builders are realistic, not just theoretically supported.\n\n## Goals\n\n- Preserve compatibility by keeping the classic builder as the default.\n- Avoid hiding behavior changes behind heuristics.\n- Let performance work continue through explicit opt-in builders.\n- Give advanced users a supported way to customize builder behavior.\n- Keep pane-readiness policy independent from builder architecture.\n\n## Non-goals\n\n- Do not merge the parallel behavior into the default builder as part of the base PR.\n- Do not require the chain builder experiment to be production-ready before defining the classic-builder selection path.\n- Do not make async execution required in the first interface PR.\n- Do not remove existing plugin lifecycle hooks or progress callbacks.\n\n## Acceptance criteria\n\n- A base PR exists that keeps classic behavior as the default and supports selecting a builder class by Python dotted path.\n- Follow-up issues exist for the builder protocol / entry points, pane-readiness configuration, parallel builder, and developer documentation.\n- Public docs explain the classic builder default and how custom builders can be configured.\n- Existing workspace files continue to load with classic behavior unless they opt into a different builder.\n","author":{"url":"https://github.com/tony","@type":"Person","name":"tony"},"datePublished":"2026-06-27T23:16:36Z","url":"https://github.com/tmux-python/tmuxp/issues/1058"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:df4e58b9-88d0-f30e-8808-c8a2f790a601 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | CD9E:172DDC:4F3953:6B6690:6B0071B6 |
| html-safe-nonce | ffababbc321379757c5419b55fd30144dc92f2153253172801061fe551263009 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJDRDlFOjE3MkREQzo0RjM5NTM6NkI2NjkwOjZCMDA3MUI2IiwidmlzaXRvcl9pZCI6IjU0MTYzMjMzNzgzNDY3NTAzOTAiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | 5fba82f4ad871e8ad5a539c9dc328337bb342d3bf161d73736f14fb56d50a541 |
| hovercard-subject-tag | issue:4760294281 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/tmux-python/tmuxp/1058/issue_layout |
| twitter:image | https://opengraph.githubassets.com/52d8085ea2214f5b024624df2db36b08254947fc43e398acc096496dca5f2386/tmux-python/tmuxp/issues/1058 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/52d8085ea2214f5b024624df2db36b08254947fc43e398acc096496dca5f2386/tmux-python/tmuxp/issues/1058 |
| og:image:alt | 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... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | tony |
| hostname | github.com |
| expected-hostname | github.com |
| None | 75c2b65dd205f26961d0c29afed1a8d0bb7cca9f05780571dfd1ef93eb539d16 |
| turbo-cache-control | no-preview |
| go-import | github.com/tmux-python/tmuxp git https://github.com/tmux-python/tmuxp.git |
| octolytics-dimension-user_id | 37234308 |
| octolytics-dimension-user_login | tmux-python |
| octolytics-dimension-repository_id | 12398170 |
| octolytics-dimension-repository_nwo | tmux-python/tmuxp |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 12398170 |
| octolytics-dimension-repository_network_root_nwo | tmux-python/tmuxp |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 84e563eb4b55f8fa102f325f117533cee9e3df4a |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width