tmux-hidden-panes Documentation
Hide the pane, keep the process.
tmux-hidden-panes lets you temporarily remove any running tmux pane from a
crowded workspace without killing the process inside it. Later, restore it from
a popup list with its label, original window, layout position, and dimensions.
- Developers running editors, tests, AI agents, or file managers in panes
- Operators keeping SSH sessions, logs, dashboards, and monitors alive
- tmux users who want less visual clutter without losing process state
- Users of tmux-resurrect or tmux-continuum who need hidden panes after restart
- A hide and restore workflow for arbitrary panes
- Labeled, persistent pane stashes with a fast last-pane toggle
- Layout-aware restoration into the original workspace
- A status bar indicator for hidden-pane count
- Restart recovery using tmux-resurrect sidecars
Core Model
tmux does not have a native hidden-pane object. The plugin moves a pane into a
Learning Path
| Module | Focus | Outcome |
|---|---|---|
| 1. Getting Started | Install and first pane hide | A working popup workflow |
| 2. Core Workflow | Labels, picker, quick toggle | Fast daily use |
| 3. Layout and Workspace | Layout recovery and status count | Predictable workspace restoration |
| 4. Persistence and Recovery | Resurrect and Continuum | Hidden panes after restart |
| 5. Configuration and Troubleshooting | Options and diagnosis | Safe customization and repairs |
| 6. Reference | Keys, files, commands, limitations | Operational reference |
Key Bindings at a Glance
| Binding | Action |
|---|---|
prefix + H | Label and hide the focused pane |
prefix + h | Open the picker and restore a selected pane |
prefix + T | Restore the latest hidden pane, or hide the focused pane when none are hidden |
prefix + C-s | Save through the Resurrect wrapper when available |
prefix + C-r | Restore through the Resurrect wrapper when available |
This server uses Ctrl+Space as the tmux prefix. Therefore prefix + H means
Ctrl+Space, release, then Shift+H.
What Persists
During the same tmux server lifetime, the plugin preserves the live process.
For example, a hidden ssh, yazi, btop, or opencode pane continues
running in __hidden__.
With tmux-resurrect integration, the plugin also persists metadata required to reconstruct the hidden-pane workflow after a tmux restart. Processes themselves must still be supported by Resurrect to restart.
Next Step
Start with Installation and First Hide.