Resurrect and Continuum

During one tmux server lifetime, hidden panes keep their live process. A tmux server restart is different: tmux-resurrect recreates panes with new pane and window IDs. The hidden-pane plugin integrates with Resurrect so it can rebuild its metadata safely after this ID change.

Why a Sidecar Is Needed

Runtime metadata references live tmux IDs such as %272 and @73. Those IDs are not stable after restart.

For every retained Resurrect snapshot, the plugin writes a private sidecar:

~/.local/share/tmux/resurrect/
├── tmux_resurrect_20260726T024202.txt
├── tmux_resurrect_20260726T024202.txt.hidden-panes
└── last -> tmux_resurrect_20260726T024202.txt

The sidecar is mode 0600, checksummed against its exact snapshot, and stores restart-stable session/window/pane coordinates plus hidden-pane metadata.

Required Plugin Order

Load tmux-resurrect before tmux-hidden-panes:

~/.tmux.conf

set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @plugin 'git@github.com:donnyaw/tmux-hidden-panes.git'

The hidden-pane plugin then replaces the public Resurrect script paths with wrappers and rebinds prefix + C-s and prefix + C-r.

Verify the active paths:

tmux show-option -gqv @resurrect-save-script-path
tmux show-option -gqv @resurrect-restore-script-path

Expected output ends with:

tmux-hidden-panes/scripts/resurrect-save.sh
tmux-hidden-panes/scripts/resurrect-restore.sh

Save and Restore Workflow

Save

Press prefix + C-s to save through the wrapper. It:

1. Acquires the shared hidden-pane operation lock.
2. Captures current hidden pane metadata.
3. Runs the real tmux-resurrect save script.
4. Verifies the retained snapshot matches the captured hidden panes.
5. Writes the checksummed sidecar.
6. Optionally archives the snapshot and sidecar together.

Restore

After a reboot, crash, or tmux-server restart:

1. Start or attach to tmux.
2. Let Continuum restore automatically, or press prefix + C-r.
3. tmux-resurrect recreates sessions, windows, and panes.
4. The wrapper maps sidecar coordinates to the newly allocated IDs.
5. Hidden panes remain in __hidden__ and appear in prefix + h.

The restore wrapper does not automatically rejoin hidden panes. You choose when

Process Recovery Expectations

Resurrect recreates terminal panes; it does not preserve arbitrary process memory. Add programs that should restart:

set -g @resurrect-processes 'yazi opencode ssh btop visidata python3'

Process Type	After tmux Restart
Supported command in @resurrect-processes	Resurrect attempts to restart it
Ordinary shell pane	Shell is recreated; previous in-memory commands are gone
SSH session	Reconnect behavior depends on Resurrect strategy and SSH configuration
Long-running process without recovery support	Must be managed separately, for example by systemd or a service manager

Archive Integration

Configure an empty plugin-owned archive root:

set -g @hidden-panes-resurrect-archive-dir "$HOME/backups/tmux-hidden-panes"

The plugin writes an ownership marker on first use and stores snapshots in dated directories. Matching sidecars are archived with their snapshots. Files matching the archive pattern are pruned after 60 days.

warning

Do not use a shared backup directory. The archive root must be empty on first use so the plugin can mark it as its own managed retention directory.

Safety Behavior

Hide, restore, and Resurrect wrappers use one advisory lock. This prevents a snapshot from being captured while a pane is moving between a visible window and __hidden__.

If a sidecar is missing, corrupt, mismatched, or ambiguous, the plugin leaves the ordinary Resurrect result intact rather than attaching metadata to the wrong pane.

Next Step

Continue with Configuration and Troubleshooting.