Layout Priority and Dimension Constraints
tmux-resurrect prioritizes the saved layout geometry—typically stored as relative percentages or split positions—but it is ultimately bound by the physical constraints of the active terminal emulator. When a session is restored, tmux attempts to map the saved coordinates onto the current available grid. If the terminal window is smaller than the saved configuration, tmux cannot force the original geometry to render.
Behavior Under Size Constraints
When the current terminal is smaller than the minimum required size for the saved pane configuration, the following behaviors occur:
- Pane Collapsing: tmux will attempt to shrink panes to fit the width. If a pane reaches a minimum width of one cell, subsequent panes may overlap or the layout may fail to render specific splits correctly.
- Layout Fallback: If the saved layout is mathematically impossible within the current window dimensions, tmux may revert to a default tiled layout or stack panes vertically to ensure all processes remain visible.
- Coordinate Distortion: Because layouts often use relative percentages, a 50/50 split in a 2000px window will look vastly different in an 800px window, potentially making text-heavy panes unreadable.
Steps to Maintain Layout Consistency
To minimize layout shifts when switching between terminal environments, follow these practices:
- Standardize Terminal Size: Ensure your terminal emulator is maximized or set to a consistent resolution before running
tmux-resurrect S.
- Use Percentage-Based Layouts: Ensure your
tmux.conf focuses on relative splits rather than fixed cell counts. This allows tmux to scale the layout proportionally across different resolutions.
- Manual Post-Restore Adjustment: If the layout appears broken after restoration, use
Ctrl-b + Space (the default layout cycle command) to force tmux to re-calculate pane boundaries based on the current dimensions.
Assumptions and Uncertainty
This analysis assumes you are using the standard tmux-resurrect plugin. There is uncertainty regarding how specific versions of tmux handle the "minimum cell width" constraint during a rapid resize; in some edge cases, resizing the window during the restoration process can cause the plugin to lose the layout string entirely.
Diagnostic Question: Are you experiencing the layout shift immediately upon restoration, or does it happen when you manually resize the window after the session has loaded?
tmux