Layout Restoration and Status

The plugin is designed to restore more than a process. It records the original window layout and semantic pane ordering before a pane is hidden.

Layout Restoration

Example starting layout:

┌───────────────────────┬───────────────────┐
│ editor                │ logs              │
│                       ├───────────────────┤
│                       │ agent             │
└───────────────────────┴───────────────────┘

If logs is hidden, the editor gains space. On restore, the plugin attempts to put logs back in its original top-right region and restore the dimensions.

The saved state includes:

• Original session and window identity
• tmux layout tree
• Pane order in the layout
• Original pane title
• Placeholder relationship for a final-pane hide

Restore Rules

Situation	Restore Behavior
Original window and sibling panes still exist	Restore original position and dimensions
Original window exists but its pane structure changed	Restore to original window; layout may be best effort
Original window was deleted	Restore into the window where you opened the picker
Original session/window coordinate is no longer valid	Restore into the current picker window

note

tmux layout strings contain pane IDs, but pane IDs are not stable across a server restart. The plugin preserves semantic pane ordering so the correct application returns to the correct layout region after ID remapping.

Full-Screen TUIs and Redraws

Hiding or restoring a pane changes terminal dimensions for its siblings. Applications such as yazi, btop, and full-screen editors may need a terminal resize event before they repaint correctly.

After every hide or restore, the plugin:

1. Notifies foreground pane process groups with SIGWINCH.
2. Refreshes the invoking tmux client immediately.
3. Repeats resize notification and refresh after short delays.

This reduces stale borders, blank regions, and late repainting after a layout change.

Hidden Count in the Status Bar

The count script emits an orange H:n only when there are hidden panes.

"current pane title" H:3

At zero hidden panes, the indicator disappears entirely.

Append it to an existing status-right value:

set -ag status-right '#(~/.tmux/plugins/tmux-hidden-panes/scripts/hidden-count.sh)'

Or replace a date/time area:

set -g status-right '"#{=21:pane_title}"#(~/.tmux/plugins/tmux-hidden-panes/scripts/hidden-count.sh)'

Reload after editing:

tmux source-file ~/.tmux.conf

Inspect Current Hidden Panes

The supported user interface is the picker, but these commands are useful for diagnosis:

# Count hidden panes
tmux list-panes -s -t __hidden__ -F '#{pane_id}' | wc -l

# Inspect hidden pane names and commands
tmux list-panes -s -t __hidden__ \
  -F '#{pane_id} | #{window_name} | #{pane_current_command}'

# Print the status-bar fragment
~/.tmux/plugins/tmux-hidden-panes/scripts/hidden-count.sh

Next Step

Continue with Resurrect and Continuum.