Command and Data Reference
Binding Reference
| Binding | Script or tmux Action | Notes |
|---|---|---|
prefix + H | hide-pane.sh | Prompts for a label |
prefix + h | list-hidden.sh | Opens fzf popup |
prefix + T | toggle-last.sh | Restores newest hidden pane or hides current pane |
prefix + C-s | resurrect-save.sh | Active only with valid tmux-resurrect integration |
prefix + C-r | resurrect-restore.sh | Active only with valid tmux-resurrect integration |
Script Reference
| Script | Purpose |
|---|---|
tmux-hidden-panes.tmux | Plugin entry point, bindings, and Resurrect wrapper setup |
scripts/hide-pane.sh | Labels and moves a focused pane into storage |
scripts/list-hidden.sh | Builds picker rows and restores a selected pane |
scripts/restore-pane.sh | Rejoins a pane, restores layout, and removes placeholders |
scripts/toggle-last.sh | Implements latest-pane quick toggle |
scripts/hidden-count.sh | Emits H:n for status-right when count is nonzero |
scripts/resurrect-save.sh | Locked Resurrect save wrapper and sidecar creation |
scripts/resurrect-restore.sh | Locked Resurrect restore wrapper and metadata reconciliation |
scripts/resurrect-sidecar.sh | Captures, validates, remaps, and restores sidecar metadata |
scripts/archive-resurrect.sh | Archives matching snapshot and sidecar pairs |
Runtime Files
| Path | Contents | Sensitivity |
|---|---|---|
~/.config/tmux-hidden-panes/list | Runtime pane metadata and layout state | Local implementation state |
~/.config/tmux-hidden-panes/operation.lock | Advisory lock for pane and snapshot mutations | Temporary coordination state |
~/.local/share/tmux/resurrect/*.txt.hidden-panes | Checksummed metadata sidecars | Private, mode 0600 |
__hidden__ tmux session | Actual hidden panes and running processes | Live 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
| Limit | Meaning |
|---|---|
| No native tmux hidden panes | The storage session can appear in generic tmux listings |
| No process-memory checkpoint | A restart only recreates commands that Resurrect supports |
| Best-effort layout fallback | Original layout requires compatible source window and siblings |
| Linux-focused persistence integration | Uses flock, GNU grep, sha256sum, and realpath |
| Private repo installation | TPM 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