Configuration and Troubleshooting

Configuration Reference

Set options before TPM loads the plugin.

~/.tmux.conf

# Key bindings
set -g @hidden-panes-hide-key 'H'
set -g @hidden-panes-list-key 'h'
set -g @hidden-panes-toggle-key 'T'

# Detached storage session
set -g @hidden-panes-session-name '__hidden__'

# Nonstandard Resurrect paths, only when needed
set -g @hidden-panes-resurrect-save-upstream \
  "$HOME/.tmux/plugins/tmux-resurrect/scripts/save.sh"
set -g @hidden-panes-resurrect-restore-upstream \
  "$HOME/.tmux/plugins/tmux-resurrect/scripts/restore.sh"

# Optional dedicated archive root
set -g @hidden-panes-resurrect-archive-dir "$HOME/backups/tmux-hidden-panes"

Option	Default	Purpose
@hidden-panes-hide-key	H	Key used to label and hide a pane
@hidden-panes-list-key	h	Key used to open the picker
@hidden-panes-toggle-key	T	Key used for latest-pane quick toggle
@hidden-panes-session-name	__hidden__	Detached tmux storage session
@hidden-panes-resurrect-save-upstream	Standard Resurrect save script	Original save script wrapped by the plugin
@hidden-panes-resurrect-restore-upstream	Standard Resurrect restore script	Original restore script wrapped by the plugin
@hidden-panes-resurrect-archive-dir	Unset	Plugin-owned archive root for snapshots and sidecars

Reload Configuration

After changing configuration:

tmux source-file ~/.tmux.conf

Check the resulting bindings:

tmux list-keys -T prefix H
tmux list-keys -T prefix h
tmux list-keys -T prefix T

Troubleshooting Table

Symptom	Likely Cause	Fix
no hidden panes	No pane has been hidden yet	Hide one first with prefix + H
H opens the wrong action	Upper/lowercase confusion	Use uppercase H to hide and lowercase h to list
Hidden pane does not return to original layout	Original window/panes changed or were deleted	Restore into current window; rebuild layout manually if needed
Window disappears after final-pane hide	Final-pane confirmation was not accepted or placeholder was killed	Restore the pane from picker; do not manually kill active placeholders
yazi or another TUI paints late	Application-specific redraw behavior	Reload plugin; switch/focus pane once if the application still ignores resize events
Resurrect restores panes but picker is empty	Sidecar missing, invalid, or wrappers not active	Verify wrapper paths and snapshot sidecar
TPM cannot install plugin	Private repo SSH access missing	Test ssh -T git@github.com and use SSH plugin URL

Diagnose Hidden State

# Runtime metadata
cat ~/.config/tmux-hidden-panes/list

# Storage session panes
tmux list-panes -s -t __hidden__ \
  -F '#{pane_id} | #{window_name} | #{pane_current_command}'

# Number of hidden panes
~/.tmux/plugins/tmux-hidden-panes/scripts/hidden-count.sh

warning

The runtime list file is implementation state. Do not edit it by hand while

Diagnose Resurrect Integration

# Wrappers must be active
tmux show-option -gqv @resurrect-save-script-path
tmux show-option -gqv @resurrect-restore-script-path

# Latest snapshot and matching sidecar
snapshot=$(readlink -f ~/.local/share/tmux/resurrect/last)
printf '%s\n' "$snapshot"
ls -l "${snapshot}.hidden-panes"

The sidecar should be private:

stat -c '%a %n' "${snapshot}.hidden-panes"

Expected permissions are 600.

Reset a Broken Test Environment

Only use this if you intentionally want to discard hidden-pane metadata and no important pane is stored in __hidden__:

rm -f ~/.config/tmux-hidden-panes/list
tmux kill-session -t __hidden__

danger

Killing __hidden__ kills every process inside the hidden panes. First restore any pane you want to keep with prefix + h.

Next Step

Continue with Command and Data Reference.