{"id":13927002,"url":"https://github.com/alexwforsythe/tmux-which-key","last_synced_at":"2026-04-23T20:03:46.749Z","repository":{"id":211499438,"uuid":"729302108","full_name":"alexwforsythe/tmux-which-key","owner":"alexwforsythe","description":"A plugin for tmux that allows users to select actions from a customizable popup menu 🧰","archived":false,"fork":false,"pushed_at":"2024-07-08T22:43:23.000Z","size":21,"stargazers_count":177,"open_issues_count":14,"forks_count":12,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-19T10:43:14.573Z","etag":null,"topics":["tmux","tmux-plugin","tmux-plugins","tpm","tpm-plugin","tpm-plugins","which-key","whichkey"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexwforsythe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-08T21:08:51.000Z","updated_at":"2025-07-17T15:32:10.000Z","dependencies_parsed_at":"2024-07-09T03:22:32.289Z","dependency_job_id":null,"html_url":"https://github.com/alexwforsythe/tmux-which-key","commit_stats":null,"previous_names":["alexwforsythe/tmux-whichkey","alexwforsythe/tmux-which-key"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alexwforsythe/tmux-which-key","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexwforsythe%2Ftmux-which-key","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexwforsythe%2Ftmux-which-key/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexwforsythe%2Ftmux-which-key/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexwforsythe%2Ftmux-which-key/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexwforsythe","download_url":"https://codeload.github.com/alexwforsythe/tmux-which-key/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexwforsythe%2Ftmux-which-key/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32196163,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T15:28:30.493Z","status":"ssl_error","status_checked_at":"2026-04-23T15:28:29.972Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["tmux","tmux-plugin","tmux-plugins","tpm","tpm-plugin","tpm-plugins","which-key","whichkey"],"created_at":"2024-08-07T16:01:17.105Z","updated_at":"2026-04-23T20:03:46.727Z","avatar_url":"https://github.com/alexwforsythe.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# tmux-which-key\n\nA plugin for tmux that allows users to select actions from a customizable popup\nmenu. Inspired by the likes of\n[vscode-which-key](https://github.com/VSpaceCode/vscode-which-key),\n[emacs-which-key](https://github.com/justbur/emacs-which-key), and\n[which-key.nvim](https://github.com/folke/which-key.nvim), this plugin aims to\nmake users more effective at using tmux by reducing keyboard shortcut\nmemorization and increasing feature discoverability.\n\n![Demo](https://vhs.charm.sh/vhs-7cpM1K8aaWiy7CTJ8Odide.gif)\n\n\u003c!-- markdownlint-disable MD033 --\u003e\n\u003cdetails\u003e\n\u003csummary\u003eKey presses\u003c/summary\u003e\n\n| Key | Action           |\n| --- | ---------------- |\n| w   | Windows menu     |\n| /   | Split horizontal |\n\n| Key | Action     |\n| --- | ---------- |\n| p   | Panes menu |\n| h   | Left pane  |\n\n\u003c/details\u003e\n\u003c!-- markdownlint-enable MD033 --\u003e\n\n## ✨ Features\n\n- An action menu with many of the common tmux commands\n- Mnemonic layout for easy memorization\n- Easily customizable and extensible via YAML configuration\n- Support for user macros (multiple commands in one action)\n- Transient states (menus that stay open for repeated commands)\n- Runs in pure tmux script for speed\n\n### Demo\n\nHere are a few examples of the plugin in action:\n\n\u003c!-- markdownlint-disable MD033 --\u003e\n\u003cdetails\u003e\n\u003csummary\u003eNavigation\u003c/summary\u003e\n\n![Navigation](https://vhs.charm.sh/vhs-5COoRwS1Qd83LpJkVGgRUq.gif)\n\n\u003cblockquote\u003e\n\u003cdetails\u003e\n\u003csummary\u003eKey presses\u003c/summary\u003e\n\n| Key | Action           |\n| --- | ---------------- |\n| w   | Windows menu     |\n| /   | Split horizontal |\n\n| Key | Action        |\n| --- | ------------- |\n| w   | Windows menu  |\n| c   | Create window |\n\n| Key | Action          |\n| --- | --------------- |\n| w   | Windows menu    |\n| p   | Previous window |\n\n| Key | Action        |\n| --- | ------------- |\n| w   | Windows menu  |\n| w   | Select window |\n| 2   | Window 2      |\n\n\u003c/details\u003e\n\u003c/blockquote\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eChanging layouts\u003c/summary\u003e\n\n![Layouts](https://vhs.charm.sh/vhs-5AcYRFnaoxilrEOxZPNYGn.gif)\n\n\u003cblockquote\u003e\n\u003cdetails\u003e\n\u003csummary\u003eKey presses\u003c/summary\u003e\n\n| Key | Action           |\n| --- | ---------------- |\n| w   | Windows menu     |\n| /   | Split horizontal |\n\n| Key | Action         |\n| --- | -------------- |\n| w   | Windows menu   |\n| -   | Split vertical |\n\n| Key         | Action       |\n| ----------- | ------------ |\n| w           | Windows menu |\n| l           | Layouts menu |\n| l (6 times) | Next layout  |\n\n| Key | Action      |\n| --- | ----------- |\n| p   | Panes menu  |\n| p   | Select pane |\n| 0   | Pane 0      |\n\n\u003c/details\u003e\n\u003c/blockquote\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eUser macros\u003c/summary\u003e\n\n![Macros](https://vhs.charm.sh/vhs-22Bo8WL6Dyntg6grCXJ5R8.gif)\n\n\u003cblockquote\u003e\n\u003cdetails\u003e\n\u003csummary\u003eKey presses\u003c/summary\u003e\n\n| Key | Action         |\n| --- | -------------- |\n| C   | Client menu    |\n| P   | Plugins menu   |\n| u   | Update plugins |\n\n| Key | Action      |\n| --- | ----------- |\n| C   | Client menu |\n| r   | Reload      |\n\n\u003c/details\u003e\n\u003c/blockquote\u003e\n\n\u003c/details\u003e\n\u003c!-- markdownlint-enable MD033 --\u003e\n\n## 📦 Installation\n\nRequirements:\n\n- tmux\u003e=3.0\n- python\u003e=3.8 (optional)\n\n### TPM ([Tmux Plugin Manager](https://github.com/tmux-plugins/tpm/tree/master#installing-plugins))\n\nAdd the plugin to the list of TPM plugins in your `~/.tmux.conf`:\n\n```tmux\nset -g @plugin 'alexwforsythe/tmux-which-key'\n```\n\nHit `prefix` + \u003ckbd\u003eI\u003c/kbd\u003e to install and load the plugin. You'll be presented\nwith a wizard to complete the installation.\n\n### Manual installation\n\n\u003c!-- markdownlint-disable MD033 --\u003e\n\u003cdetails\u003e\n\u003csummary\u003eInstallation steps\u003c/summary\u003e\n\n1. Clone this repository flag using the `--recursive` flag:\n\n```sh\ngit clone --recursive https://github.com/alexwforsythe/tmux-which-key $HOME/.tmux/plugins/\n```\n\n2. Register the plugin in your `~/.tmux.conf`:\n\n```tmux\nrun-shell $PATH_TO_PLUGIN/plugin.sh.tmux\n```\n\n3. Reload your tmux config to load the plugin:\n\n```sh\ntmux source-file $HOME/.tmux.conf\n```\n\n\u003c/details\u003e\n\u003c!-- markdownlint-enable MD033 --\u003e\n\n## 🎬️ Quickstart\n\nOnce you've installed the plugin and reloaded your tmux config, you can open the\naction using:\n\n- The default root keybinding \u003ckbd\u003ectrl\u003c/kbd\u003e + \u003ckbd\u003espace\u003c/kbd\u003e, or\n- The default prefix keybinding `prefix` + \u003ckbd\u003espace\u003c/kbd\u003e\n\n## ⚙️ Configuration\n\nMenus can be customized either by:\n\n1. Editing `config.yaml` (requires python3), or\n2. Editing `plugin/init.tmux` directly\n\n### YAML config\n\n\u003e [!NOTE]\n\u003e\n\u003e This method requires python3 to be installed on your system. Most Unix systems\n\u003e ship with it installed by default these days, so it shouldn't be a problem for\n\u003e most users. If you don't have python3 installed and aren't willing to use it,\n\u003e you'll need to edit `plugin/init.tmux` directly.\n\nThe default configuration is defined in `config.example.yaml`. Here's the\nstructure:\n\n```yaml\n# The starting index to use for the command-alias option, used for macros\n# (required). This value must be at least 200\ncommand_alias_start_index: 200\n# The keybindings that open the action menu (required)\nkeybindings:\n  prefix_table: Space # The keybinding for the prefix key table (required)\n  root_table: C-Space # The keybinding for the root key table (optional)\n# The menu title config (optional)\ntitle:\n  style: align=centre,bold # The title style\n  prefix: tmux # A prefix added to every menu title\n  prefix_style: fg=green,align=centre,bold # The prefix style\n# The menu position (optional)\nposition:\n  x: R\n  y: P\n# tmux-only environment variables that can be used in commands and macros\n# (optional)\ncustom_variables:\n  my_var: my_value\n# User-defined macros that can be triggered by the menu (optional)\nmacros:\n  restart-pane: # The macro name\n    # The macro commands\n    - \"respawnp -k -c #{pane_current_path}\"\n    - display \"#{log_info} Pane restarted\"\n# The root menu items (required)\nitems:\n  - name: Next pane\n    key: space # The key that triggers this action\n    command: next-pane # A command to run\n  - name: Respawn pane\n    key: R\n    macro: restart-pane # A custom macro (defined above)\n  - separator: true # A menu separator\n  - name: +Layout # A submenu\n    key: l\n    menu: # The submenu items\n      - name: Next\n        key: l\n        command: nextl\n        transient: true # Whether to keep the menu open until ESC is pressed\n```\n\n#### User options\n\n##### @tmux-which-key-disable-autobuild\n\nBy default, the menu is rebuilt from `config.yaml` each time TPM initializes the\nplugin. If you aren't using the YAML configuration or want to reduce the\nplugin's impact on tmux startup time, you can disable this behavior by adding\nthis to your `~/.tmux.conf` **before** loading the plugin:\n\n```tmux\nset -g @tmux-which-key-disable-autobuild=1\n# ...\nset -g @plugin 'alexwforsythe/tmux-which-key'\n```\n\n##### @tmux-which-key-xdg-enable\n\nChanges the location of configuration and init files to use XDG directories. By\ndefault, these paths will be used instead of this plugin's installation\ndirectory:\n\n- `$XDG_CONFIG_HOME/tmux/plugins/tmux-which-key/config.yaml`\n- `$XDG_DATA_HOME/tmux/plugins/tmux-which-key/init.tmux`.\n\nThe relative path from `XDG_*_HOME` can be changed using the\n`@tmux-which-key-xdg-plugin-path` option for additional customization.\n\n```tmux\nset -g @tmux-which-key-xdg-enable=1\nset -g @tmux-which-key-xdg-plugin-path=tmux/plugins/tmux-which-key # default\n\n# ...\n\nset -g @plugin 'alexwforsythe/tmux-which-key'\n```\n\nThis allows the plugin to also be used with immutable or declarative operating\nsystems.\n\n\u003c!-- markdownlint-disable MD033 --\u003e\n\u003cdetails\u003e\n\u003csummary\u003eExample Home Manager Nix Config\u003c/summary\u003e\n\n```nix\n{\n  lib,\n  pkgs,\n  ...\n}: let\n  tmux-which-key =\n    pkgs.tmuxPlugins.mkTmuxPlugin\n    {\n      pluginName = \"tmux-which-key\";\n      version = \"2024-01-10\";\n      src = pkgs.fetchFromGitHub {\n        owner = \"alexwforsythe\";\n        repo = \"tmux-which-key\";\n        rev = \"\u003ccommit hash\u003e\";\n        sha256 = lib.fakeSha256;\n      };\n      rtpFilePath = \"plugin.sh.tmux\";\n    };\nin {\n  xdg.configFile = {\n    \"tmux/plugins/tmux-which-key/config.yaml\".text = lib.generators.toYAML {} {\n      command_alias_start_index = 200;\n      # rest of config here\n    };\n  };\n  programs.tmux.plugins = [\n    {\n      plugin = tmux-which-key;\n      extraConfig = ''\n        set -g @tmux-which-key-xdg-enable 1;\n      '';\n    }\n  ];\n}\n```\n\n\u003c/details\u003e\n\u003c!-- markdownlint-enable MD033 --\u003e\n\n\u003c!-- markdownlint-disable MD024 --\u003e\n\n### Manual config\n\nYou can customize the action menu by editing `plugin/init.tmux` directly.\n\n\u003e [!TIP]\n\u003e\n\u003e I strongly recommend using YAML to customize your action menu because editing\n\u003e tmux script can be error-prone and difficult to debug.\n\n### Zsh\n\nYou can open tmux-which-key from the command line by running its tmux alias:\n\n```sh\ntmux show-wk-menu-root\n```\n\nYou can trigger the menu with \u003ckbd\u003eSpace\u003c/kbd\u003e from vicmd mode--similarly to\n[Spacemacs](https://github.com/syl20bnr/spacemacs) or\n[VSpaceCode](https://github.com/VSpaceCode/VSpaceCode)--by adding a ZLE widget\nand keybinding to your `~/.zshrc`:\n\n```sh\ntmux-which-key() { tmux show-wk-menu-root ; }\nzle -N tmux-which-key\nbindkey -M vicmd \" \" tmux-which-key\n```\n\n## ❓ Known issues\n\n### Menu or submenu doesn't appear\n\nMenus will silently fail to open if the number of items causes them to exceed\nthe height of the terminal. If you run into this issue frequently, consider\nbreaking your menu into multiple submenus.\n\n### Plugin overrides custom aliases\n\ntmux-which-key uses tmux `command-alias` to execute certain actions, such as\nmacros, quickly. `command-alias` is a global option, though, so these actions\ncan collide with user aliases or ones defined by other plugins.\n\nThis plugin's aliases start at index 200 by default, but if there are already\naliases mapped in this range, you can change the default starting index in\n`config.yaml`.\n\n## Similar projects\n\n- [tmux-modal](https://github.com/whame/tmux-modal)\n- [tmux-menus](https://github.com/jaclu/tmux-menus)\n- [tmux-easy-menu](https://github.com/ja-sonyun/tmux-easy-menu)\n- [tmux-pain-control](https://github.com/tmux-plugins/tmux-pain-control)\n\n## Resources\n\n- `man tmux`\n- [Tmux Wiki](https://github.com/tmux/tmux/wiki)\n- [How to create Tmux plugins](https://github.com/tmux-plugins/tpm/blob/master/docs/how_to_create_plugin.md)\n- [The Tao of tmux](https://leanpub.com/the-tao-of-tmux/read)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexwforsythe%2Ftmux-which-key","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexwforsythe%2Ftmux-which-key","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexwforsythe%2Ftmux-which-key/lists"}