A collection of popup menus for managing your tmux environment. Menus can be customized with optional docs/Styling.md, as shown in the right screenshot above.
Once installed, press the trigger key to display the main menu. The default
trigger is <prefix> \ (see Configuration below to customize).
There is also a secondary default <prefix> Enter if it has not already been
bound to something else. See docs/SecondaryDefault.md
for details.
The menus are designed to be easily adaptable to your workflow. Some items may seem redundant to experienced users, but this makes it easier for newcomers to discover functionality—advanced users can simply remove what they don't need.
- Danger Zone — Destructive commands are highlighted by default; enable/disable or customize as needed
- Enhanced Floating Panes handling — New combined menu, with a toggle to split format for standard 25x80 terminals, plus new pane placement controls
- Stabilized Display Commands — Fixed crashes and improved stability when displaying menu command references
- Secondary default trigger key
<prefix> Enterfor non-US keyboards where<prefix> \is impractical
While tmux provides a few basic popup menus by default, they're quite limited and difficult to extend due to their complex, mouse-focused one-liner implementations. This plugin provides a more user-friendly approach with better navigation and extensibility.
This isn't just a beginner's tool—it's useful for experienced users too:
- Command Reference: Use
Display menu commandsas a quick reference for keyboard shortcuts. - Limited Terminals: When connecting via terminals with poor Meta key or arrow key support (like macOS's built-in Terminal), menus provide access to actions that would otherwise require unavailable shortcuts.
- Complex Operations: Simplify tasks that would otherwise require external scripts or hard-to-read bind one-liners, such as killing the current session without disconnecting.
- Efficiency: Some operations are simply faster via menus. For example,
killing the server takes 12 keystrokes via command line
(
<prefix> : kill-ser <tab> <enter>) but only 5 via menus (<prefix> \ A x y).
The white screenshot shows a whiptail-generated menu, which uses more screen space than native tmux menus. However, whiptail menus are scrollable when they don't fit the screen. The other screenshots show native tmux menus.
Floating pane handling offers both a combined menu and split menus. If the combined menu is too tall for your terminal, you can toggle to split format. This selection is remembered for the next time.
This plugin does not work when the tmux environment path contains spaces.
Left arrow doesn't work to go back. Workaround: Highlight and press Enter instead.
Still present in 3.7c - resolved in 3.8
| Version | Notes |
|---|---|
| 3.4 | Styling supported. |
| 3.2 | Full menu positioning available. |
| 3.0 - 3.1c | Menu centering not supported; displays top-left if C is selected. |
| < 3.0 | Requires whiptail or dialog (see below). Menu location and styling settings are ignored. |
| < 1.8 | TPM not available; initialize by running [path to tmux-menus]/menus.tmux directly from config file. |
| 1.5 | Minimum required version. |
These compatibility notes apply to the plugin as a whole. Individual menu items may have minimum version requirements—items incompatible with your tmux version will be automatically skipped. If you encounter incorrect version limits, please report them!
Add the plugin to your .tmux.conf:
set -g @plugin 'jaclu/tmux-menus'Press <prefix> I to install and source the plugin.
Clone the repository:
git clone https://github.com/jaclu/tmux-menus ~/path/to/tmux-menusAdd to the bottom of your .tmux.conf:
run-shell ~/path/to/tmux-menus/menus.tmuxReload your configuration:
tmux source-file ~/.tmux.confAll boolean parameters accept the following values (case-insensitive):
- True:
Yes,True,1 - False:
No,False,0
The default trigger is <prefix> \. To customize it:
set -g @menus_trigger 'Space'See docs/QuotingPitfalls.md for handling special characters like
\ in tmux variables. For more information about the secondary default and why
it was introduced, see SecondaryDefault.
set -g @menus_without_prefix 'Yes'Default: No
Enable this to trigger menus without pressing <prefix> first.
All commands that are destructive, such as kill/delete/respawn etc can be made
to standout by using a specific style. If this is not desired, set it to ""
set -g @menus_danger_zone "#[fg=red,bg=white]" # prints it red on white
set -g @menus_danger_zone "" # Disables the featureDefault: #[reverse]
set -g @menus_main_menu "~/my_tmux_menus/main.sh"Default: None (uses built-in menus)
Override the default menu system with custom menus.
Important notes:
- All custom menus must define
D_TM_BASE_PATHto point to the tmux-menus installation directory for support scripts to work correctly.
Default: C for tmux ≥ 3.2, P otherwise. Ignored when using whiptail/dialog.
set -g @menus_location_x 'W'
set -g @menus_location_y 'S'For complete location options, see the tmux man page under display-menu.
Common options:
| Value | Axis | Meaning |
|---|---|---|
| C | Both | Center of terminal (tmux ≥ 3.2) |
| R | -x | Right side of terminal |
| P | Both | Bottom-left of pane |
| M | Both | Mouse position |
| W | Both | Window position on status line |
| S | -y | Line above or below status line |
This impacts floating pane move/resize actions in the Panes - Floating Panes menu (requires tmux 3.8).
The stepping size is defined by these two settings:
set -g @menus_floating_pane_incr_horizontal 5
set -g @menus_floating_pane_incr_vertical 2Default for both: 1
set -g @menus_display_commands 'No'Default: Yes (not available when using whiptail/dialog)
When enabled, each menu includes a "Display Commands" item (shortcut !). Press it
to cycle through three views: the underlying tmux commands, all matching prefix and
root key bindings, and back to the normal menu.
This helps you discover tmux bindings and verify if an action already has a shortcut configured.
Note: Menus grow larger with this feature enabled—ensure sufficient screen space.
This option only applies when Display Menu Commands is enabled above.
set -g @menus_display_cmds_cols 160Default: 75
Controls the maximum line length for displayed commands. Long commands are split into chunks at whitespace when possible, or at the maximum length if no whitespace is found.
If lines end with >, they've been truncated by tmux because they exceed the
display width. Reduce @menus_display_cmds_cols to prevent truncation.
Usually the default (below) is sufficient, but you can configure it if needed:
set -g @menus_config_file "~/.configs/tmux.conf"See QuotingPitfalls for handling $HOME and ~ in tmux
variables.
The main menu includes a reload option that needs to know which config file to reload. The location is determined in this order:
@menus_config_file- if defined in your tmux config$TMUX_CONF- if present in the environment$XDG_CONFIG_HOME/tmux/tmux.conf- if$XDG_CONFIG_HOMEis defined~/.tmux.conf- default fallback
When reloading, you'll be prompted to confirm the config file path, which defaults to the first match above and can be edited if needed.
For advanced settings including caching, logging, and hint overlays, see docs/Advanced.md.
In tmux versions prior to 3.8, when a menu doesn't fit on screen, tmux silently refuses to display it without raising an error—the menu simply won't appear.
To help diagnose this issue, the plugin monitors how quickly a menu closes. If it closes in less than 0.1 seconds, it displays:
tmux-menus ERROR: Screen might be too small
Note: This detection has false positives—a quick close can also mean you dismissed the menu while it was rendering. Try again to confirm. (Not an issue on tmux 3.8+.)
For tmux versions prior to 3.0, the plugin falls back to whiptail or dialog
for menu display since display-menu doesn't exist.
The plugin tries handlers in this order:
whiptail(preferred)dialog(fallback)
If neither is available, the plugin will error.
These are full-screen terminal applications that pause your session while displaying the menu.
Limitations: External handlers don't differentiate between uppercase and lowercase letters, and don't support special keys (arrow keys, Home, etc.).
Linux: Most distributions include whiptail by default. In the Red Hat
an Homebrew ecosystems, the package that contains whiptail is called newt.
macOS: Install via Homebrew: brew install newt
To use whiptail/dialog on tmux 3.0+, set an environment variable:
export TMUX_MENUS_HANDLER=1 # force whiptail
export TMUX_MENUS_HANDLER=2 # force dialogContributions are welcome and appreciated! Every contribution helps, and credit is always given.
To report bugs, request features, or provide feedback, please file an issue.
Thanks to everyone who has contributed to making this plugin better:
- shixianqin - Reported that
<prefix> \is problematic on non-US keyboards, leading to the secondary default<prefix> Enter(fixed in 2.3.0) - cmon1701 - Reported hardcoded path assumptions in plugin listing (fixed in 2.1.3)
- sumskyi - Improved boolean check error messages to include variable names (fixed in 2.0.2)
- GaikwadPratik - Reported broken cache disabling feature
- Tony Soloveyv - Caught unintentional shortcut change in main menu
- JuanGarcia345 - Suggested making menu-cache optional
- phdoerfler - Identified TMUX_BIN not being set consistently
- giddie - Suggested "Re-spawn current pane" feature
- wilddog64 - Suggested prefix for public IP curl probe