# tmux-menus: popup menus for a terminal multiplexer

> tmux-menus is a tmux plugin that adds popup menus for the things tmux exposes only as prefix commands: sessions, windows, panes, layouts and floating panes. The argument is measured in keystrokes, since killing a server costs twelve keystrokes on the command line and five through the menu, and it ships a configurable trigger key, a danger zone for destructive commands, and a whiptail fallback for older tmux versions.

**jaclu/tmux-menus** — Tmux plugin, Popup menus to help with managing your environment

- Repository: https://github.com/jaclu/tmux-menus
- Stars: 542 · Forks: 19
- Language: Shell
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/jaclu-tmux-menus

## What tmux gives you and what this replaces

tmux-menus is a collection of popup menus for managing your tmux environment, and the README is direct about the gap it fills.

While tmux provides a few basic popup menus by default, they are 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.

That is an accurate description of the state of tmux's own menus. Tmux has a display-menu command and a choose-tree command, both of which are capable and both of which are built as dense one-liner bindings with mouse support. They are hard to extend because there is no structure to extend: you get a list of entries and a set of key bindings, and adding an entry means editing a long string.

This plugin takes the other approach. The menus are shell scripts that run tmux commands, laid out in a tree, and the tree is where the value is. A menu for handling a pane leads to a menu for choosing what to do with it, and each of those is a line in a file rather than a fragment of a one-liner.

The audience is described with some care. The README says this is not just a beginner's tool, it is useful for experienced users too, and then lists four reasons: a command reference, because Display menu commands acts as a quick reference for keyboard shortcuts; limited terminals, because terminals with poor Meta key or arrow key support, such as the macOS built-in Terminal, make some actions unreachable by shortcut; complex operations, where the menu replaces an external script or a hard-to-read bind one-liner, such as killing the current session without disconnecting; and efficiency, because some operations are simply faster through the menu.

The licences and packaging are simple. The project is MIT licensed, the primary language is Shell, and the topics are tmux, tmux-plugin, display-menu and popup-dialog.

## The trigger keys, and why there are two

Once installed, you press the trigger key to display the main menu. The default trigger is the prefix followed by a backslash, and it can be changed in the configuration:

```tmux
set -g @menus_trigger 'Space'
```

There is also a secondary default, prefix followed by Enter, if it has not already been bound to something else. That secondary binding exists for a reason the README explains in its recent changes list: it is the secondary default trigger key for non-US keyboards where the prefix followed by a backslash is impractical.

That is a small detail with a large audience. On many keyboard layouts a backslash is not where a US layout puts it, and on a layout where it is somewhere awkward, binding the menu to a key you can reach without moving your hand changes whether the plugin is usable at all. The secondary binding is the fallback, and it is only bound if nothing else already claims it.

There is also an option to trigger the menus without the prefix at all:

```tmux
set -g @menus_without_prefix 'Yes'
```

whose default is No. That is a bolder change, since it makes a key open a menu with no prefix, and it is the kind of setting that can conflict with an application running inside tmux. The plugin also documents a quoting pitfalls page for people who want to use special characters such as a backslash in tmux variables, which is the sort of thing that wastes an evening if it is not written down.

The configuration parameters are booleans that accept a case-insensitive set of values: Yes, True and 1 for true, and No, False and 0 for false. That is worth noting because tmux variables are strings, and a plugin that silently treated any non-empty value as true would be unusable.

## Twelve keystrokes against five

The README makes its case with a specific comparison, and it is the clearest statement of the plugin's value.

Some operations are simply faster via menus. Killing the server takes twelve keystrokes via the command line, the prefix, a colon, kill-ser, tab and enter, but only five via menus: the prefix, the backslash, and then three letters that walk down the menu tree.

That is the arithmetic, and it generalises. A tmux user who has internalised their own bindings is faster with bindings than with a menu, and the plugin does not pretend otherwise. The menu wins in three situations. When you do not remember the exact command, because the menu shows you the choices. When the command has a complex form, because the menu has already worked out the arguments. And when the terminal you are connected through does not deliver the keys you need.

That last case is the one that makes it more than a convenience. The README names terminals with poor Meta key or arrow key support, and the macOS built-in Terminal as the example. If the Meta key does not arrive at the remote end, then a binding that depends on the Meta key does not work at all, and every alternative is a long sequence of prefix combinations you have to remember. A menu driven by the arrow keys or by selection does.

There is also a discovery argument that the README makes. Some items may seem redundant to experienced users, but this makes it easier for newcomers to discover functionality, and advanced users can simply remove what they do not need. The menu tree is a browsable map of what the plugin can do, and it doubles as documentation, which is why Display menu commands exists as an item in its own right.

## Native menus, whiptail and the version table

The plugin draws its menus in one of two ways, and which one depends on your tmux version, which is why the README spends a paragraph on the difference.

The white screenshot shows a whiptail-generated menu, which uses more screen space than native tmux menus. However, whiptail menus are scrollable when they do not fit the screen. The other screenshots show native tmux menus.

That is the trade. A native tmux menu is drawn inside the terminal, respects the pane geometry and looks like tmux, but it does not scroll and a long menu can be cut off. A whiptail menu is a separate program drawing over the terminal, so it can scroll and can show more entries, but it takes the whole screen and does not look like anything else in tmux.

The compatibility table is the most useful part of the README for deciding, and it is unusually precise:

Version 3.4 supports styling. Version 3.2 has full menu positioning available. Versions 3.0 to 3.1c do not support menu centering and display top-left if C is selected. Anything below 3.0 requires whiptail or dialog, and the menu location and styling settings are ignored. Anything below 1.8 has no TPM, so you initialise by running the menus.tmux file directly from your config file. Version 1.5 is the minimum required version.

The README also notes that these notes apply to the plugin as a whole, that individual menu items may have their own minimum version requirements, and that items incompatible with your tmux version will be automatically skipped.

That last point is a good design decision and a good piece of advice. A plugin that silently drew the wrong thing on an old version would be worse than one that leaves out the parts it cannot support.

## The Danger Zone and the floating pane work

The recent changes section describes what has been worked on lately, and two items stand out.

The Danger Zone covers destructive commands. All commands that are destructive, such as kill, delete or respawn, can be made to stand out. The README says they are highlighted by default and that you can enable, disable or customise it as needed.

That is a small feature with an obvious purpose. A menu that can kill your session is a menu where a stray keypress has consequences, and marking the dangerous entries so they look different is the difference between a menu you use confidently and a menu you check before pressing.

The second is enhanced floating pane handling. Floating pane handling offers both a combined menu and split menus, and if the combined menu is too tall for your terminal you can toggle to split format. The README adds that there is a split format for standard 25 by 80 terminals and new pane placement controls, and that the selection is remembered for the next time.

The remembering detail is the interesting one. A floating pane menu with placement choices is a menu you use repeatedly, and a setting that resets every time is a setting you would set once and then work around. Remembering it makes the second use of the menu cheaper.

Two more items are in the list. Stabilized display commands fixes crashes and improves stability when displaying menu command references, which matters because the command reference is the item that experienced users are most likely to open. And the secondary default trigger key for non-US keyboards, described earlier.

The repository itself is a shell project with menus.tmux at the root as the entry point, items/ for the menu entries, templates/ and tools/ for the generation and helper machinery, scripts/, docs/ for the per-topic pages, a CHANGELOG.md, a TODO.md, a .shellcheckrc for linting the shell code and .markdownlint.json, .olint.conf and .prettierignore for the documentation, and a pyproject.toml that configures the pymarkdown formatter.

## Installing it, and what the plugin actually is

There are two installation routes, and the plugin manager route is the recommended one.

Via TPM, you add the plugin to your .tmux.conf:

```tmux
set -g @plugin 'jaclu/tmux-menus'
```

and then press the prefix followed by I to install and source the plugin.

The manual route is three steps. Clone the repository:

```bash
git clone https://github.com/jaclu/tmux-menus ~/path/to/tmux-menus
```

add a line to the bottom of your .tmux.conf:

```tmux
run-shell ~/path/to/tmux-menus/menus.tmux
```

and reload the configuration:

```bash
tmux source-file ~/.tmux.conf
```

The run-shell line is the whole plugin. It executes a shell script that defines the menus and binds the keys, which is the tmux plugin convention and the reason TPM can install it without any special support.

What that means for what the plugin is: it is not a daemon and it does not run in the background. It is a set of tmux commands and key bindings that are constructed when your configuration loads, and it works by sending the same tmux commands you would type, only chosen from a menu instead of from memory. There is no state to lose and nothing to stop, which is a real advantage over a plugin that keeps a process running.

The last push to the repository was on 2026-10-19, the default branch is main, and the project publishes no GitHub releases, so the plugin is installed from the repository rather than from a versioned artefact.

## Where tmux-menus is the wrong choice

There are clear cases where this plugin is not the answer, and the README lists two of them itself.

The first is a hard incompatibility: this plugin does not work when the tmux environment path contains spaces. There is no configuration setting for that, and it is the kind of limitation that either does not affect you or makes the plugin unusable.

The second is a bug in tmux itself rather than in the plugin. In tmux 3.7 the left arrow does not work to go back in the display menu. The workaround is to highlight the entry and press Enter instead. The README notes it was still present in 3.7c and that it was resolved in 3.8, so if you are on 3.7 you either live with it or upgrade tmux.

Beyond those, the question is whether menus are the right interface for you at all. If you have internalised your tmux bindings, the menu is slower than what you already know, and the plugin's own argument is that it is for people who have not. The efficiency example in the README makes the point in the other direction: the command line is twelve keystrokes and the menu is five, but five keystrokes of muscle memory is faster than five keystrokes of navigation, and the difference only shows in the menu's favour when you do not remember the command.

The alternative approach is a set of your own bindings, possibly generated by a tmux configuration framework, which gives you the same speed with none of the menu machinery. The difference in approach is that a binding is a fixed command and a menu is a browsable tree: the menu is better for discovery and for one-off operations, the binding is better for repetition, and a serious tmux user ends up with both.

There is also the question of what the menus run. They are shell scripts that invoke tmux commands, so they inherit your tmux configuration and they act on the session you are in. That is what makes them useful and it is also what makes them worth thinking about before you bind them to a key that is one stray keystroke away from a destructive command.

## Conclusion

tmux-menus suits a tmux user on a keyboard without a good Meta key or working arrow keys, and anybody who has more than one session and spends time moving between them. It does not suit somebody who wants to be faster than the menus are, since the fastest route is still a key binding, and it does not suit a setup whose tmux environment path contains spaces, which the README lists as a known limitation. Check three things before you install it: that your tmux version is at least 1.5, that your tmux is 3.8 or newer if you want to avoid the display-menu arrow key bug present in 3.7, and that you are on tmux 3.2 or newer if you want menu positioning, since older versions fall back to whiptail and ignore the location and styling settings. The last push to the repository was on 2026-10-19 and the project publishes no GitHub releases.

## FAQ

### What does tmux-menus do?

It provides popup menus for managing a tmux environment, covering sessions, windows, panes, layouts and floating panes. The README's argument is that tmux's own popup menus are limited and hard to extend because they are complex, mouse-focused one-liner implementations, and that menus are faster for some operations and reachable on terminals with poor key support.

### How do I install tmux-menus with TPM?

Add set -g @plugin 'jaclu/tmux-menus' to your .tmux.conf and press the prefix followed by I to install and source it. For a manual install, clone the repository, add a run-shell line pointing at menus.tmux to the bottom of your .tmux.conf, and reload with tmux source-file ~/.tmux.conf.

### Which tmux versions does tmux-menus support?

Version 1.5 is the minimum. Styling needs 3.4, full menu positioning needs 3.2, versions 3.0 to 3.1c have no centering, and anything below 3.0 requires whiptail or dialog and ignores the location and styling settings, while below 1.8 there is no TPM so you initialise the plugin from your config file.

### What are the known limitations of tmux-menus?

The plugin does not work when the tmux environment path contains spaces, and in tmux 3.7 the left arrow does not go back in the display menu, with the workaround being to highlight the entry and press Enter, a bug the README says was resolved in 3.8.

### How do I change the tmux-menus trigger key?

Set @menus_trigger in your tmux.conf, for example set -g @menus_trigger 'Space'. The default is the prefix followed by a backslash, there is a secondary default of the prefix followed by Enter for non-US keyboards, and @menus_without_prefix set to Yes triggers the menus without the prefix, with No as the default.

## Sources

- [Issues](https://github.com/jaclu/tmux-menus/issues)
- [jaclu/tmux-menus on GitHub](https://github.com/jaclu/tmux-menus)
- [License: MIT](https://github.com/jaclu/tmux-menus/blob/main/LICENSE)
- [README](https://github.com/jaclu/tmux-menus/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jaclu-tmux-menus