Skip to main content

Command and Data Reference

Binding Reference​

BindingScript or tmux ActionNotes
prefix + Hhide-pane.shPrompts for a label
prefix + hlist-hidden.shOpens fzf popup
prefix + Ttoggle-last.shRestores newest hidden pane or hides current pane
prefix + C-sresurrect-save.shActive only with valid tmux-resurrect integration
prefix + C-rresurrect-restore.shActive only with valid tmux-resurrect integration

Script Reference​

ScriptPurpose
tmux-hidden-panes.tmuxPlugin entry point, bindings, and Resurrect wrapper setup
scripts/hide-pane.shLabels and moves a focused pane into storage
scripts/list-hidden.shBuilds picker rows and restores a selected pane
scripts/restore-pane.shRejoins a pane, restores layout, and removes placeholders
scripts/toggle-last.shImplements latest-pane quick toggle
scripts/hidden-count.shEmits H:n for status-right when count is nonzero
scripts/resurrect-save.shLocked Resurrect save wrapper and sidecar creation
scripts/resurrect-restore.shLocked Resurrect restore wrapper and metadata reconciliation
scripts/resurrect-sidecar.shCaptures, validates, remaps, and restores sidecar metadata
scripts/archive-resurrect.shArchives matching snapshot and sidecar pairs

Runtime Files​

PathContentsSensitivity
~/.config/tmux-hidden-panes/listRuntime pane metadata and layout stateLocal implementation state
~/.config/tmux-hidden-panes/operation.lockAdvisory lock for pane and snapshot mutationsTemporary coordination state
~/.local/share/tmux/resurrect/*.txt.hidden-panesChecksummed metadata sidecarsPrivate, mode 0600
__hidden__ tmux sessionActual hidden panes and running processesLive tmux state

Sidecar Lifecycle​

Data Boundaries​

The plugin does not save terminal output directly. Resurrect's own @resurrect-capture-pane-contents option controls pane-content capture and is separate from hidden-pane metadata.

The plugin records metadata necessary to restore workflow state, including labels, timing, pane identity tokens, original layout, and stable Resurrect coordinates.

Operational Limits​

LimitMeaning
No native tmux hidden panesThe storage session can appear in generic tmux listings
No process-memory checkpointA restart only recreates commands that Resurrect supports
Best-effort layout fallbackOriginal layout requires compatible source window and siblings
Linux-focused persistence integrationUses flock, GNU grep, sha256sum, and realpath
Private repo installationTPM must authenticate with GitHub SSH while the repo remains private

Useful Commands​

# Reload configuration
tmux source-file ~/.tmux.conf

# Show the current storage session
tmux list-panes -s -t __hidden__ \
-F '#{pane_id} | #{window_name} | #{pane_current_command}'

# Verify status count
~/.tmux/plugins/tmux-hidden-panes/scripts/hidden-count.sh

# Verify Resurrect wrappers
tmux show-option -gqv @resurrect-save-script-path
tmux show-option -gqv @resurrect-restore-script-path

# Run the isolated integration test from the plugin repository
cd ~/github/cli-projects/tmux-hidden-panes