menu - menu and popup menu system for weechat (weechat edition)




to open the main menu or (recommended) add a key binding to open the menu. For example,

  /key bind meta-m /menu

would allow you to open the menu with Alt+M.

If your WeeChat comes with builtin cursor and mouse support, you can bind the nick popup menu to the nicklist using

  /key bindctxt mouse @item(buffer_nicklist):button1 hsignal:menu

or if you want to use cursor mode, you can bind it to a key like this:

  /key bindctxt cursor @item(buffer_nicklist):m hsignal:menu;/cursor stop


menu will give you a main menu and a popup menu to be able to use some features through menu entries. A popup menu for the nicklist is included by default.


to open the main menu, hit the key you defined as a keybinding as explained in the "SYNOPSIS" or type /menu.

Menu navigation

after you open the main menu, you will be able to choose the main menu entry using the left-arrow and right-arrow keys of your keyboard. You can also type the underlined letters for quick access. To open a submenu, just press the Return key while the menu entry is highlighted.


Once you have opened a submenu, use the up-arrow and down-arrow to choose a menu entry. To run a menu entry, confirm with Return again.

to close any menu, type Ctrl+X on your keyboard.

for mouse support, this script will listen to mouse input signals. You need WeeChat with builtin cursor and mouse support.

Nick menu

There is a popup menu for nick names which can be opened using

  /menu nick NICKNAME

whereby NICKNAME has to be replaced by a real nick. More conveniently, when using the mouse this command is bound to clicks on the nicklist so you can just click on a nick in the nicklist to open this popup menu. It is navigated in the same way as a submenu.




the settings are usually found in the

namespace, that is, type


to see them and

  /set VALUE

to change a setting SETTINGNAME to a new value VALUE. Finally,


will reset a setting to its default value.

the following settings are available:


if this is set to on, a submenu is not closed when the entry is confirmed but has to be closed manually using Ctrl+X.


this setting is documented for completeness, it reflects if the help bar is visible and can be toggled from within the menu with Ctrl+H.


if set to on, the friendly reminder how to open the main menu (by default: /menu to open menu) will be removed from view. useful for those people bothered by it.


if set to on, the main menu bar will be always hidden. useful if you don't care about clicking on the main menu and want to save one line on your screen (due to internal reasons, the setting does not work reliably, use this instead.)


the whole menu is configurable through the file menu.conf or

  /set menu.var.*

The syntax for a main menu is

  /set &Name

where # is an unique number, Name is the name of the menu and the letter after the & is the unique shortcut for this menu. All menu entries in the submenu of this menu are of the form

  /set &Item
  /set menu.var.#.1.command /command

where # is the number of the main menu, 1 is an unique number for this submenu item, Item is the name of this item, the letter after the & is the unique shortcut for this item as above. /command specifies the command to be executed, for multiple commands create an alias first.

See the included main menu for an example.

Popup menus

Popup menus are configured through

  /set menu.var.POPUP.*

where POPUP is the name of the popup menu. The popup menu entries are configured in the same way as submenu entries above, with POPUP replacing #. To open a popup menu, use

  /menu POPUP args

The value of args is available in a popup command as $0, $1, ...

See the included nick popup for an example.

Dynamic menus

Dynamic menu entries are configured through .command settings. There must not be a .name on this level for dynamic menu generation to work. The syntax is as follows:

  /set &Buffers
  /set menu.var.#.1.command "%gui_buffers.buffer% ${i} ${} % /buffer ${buffer.full_name}"

The first part of command must be %HDATA_LIST.HDATA_NAME% (see the weechat api docs for info on hdata).

The second part sets the .name of the dynamic items and the third part sets the .command. They are seperated by % and evaluated with /eval (see /help eval for more info).

Refer to the three dynamic menus that ship with the sample config.

For usage with scripts, another form of dynamic menu is supported:

  /set menu.var.POPUP.1.command "%#info_hashtable% $1 % $0"

The first part of command must be %#INFO_HASHTABLE_NAME% (see the weechat api docs on weechat_hook_info_hashtable).

The second and third part are passed on to the hashtable function in the hashtable parameter. The returned hashtable must contain suitable 1.command/ pairs to be added into the menu.

You can check the spell_menu script for an example of how to use this.