{"id":13740604,"url":"https://github.com/whame/tmux-modal","last_synced_at":"2025-05-08T20:31:54.590Z","repository":{"id":41374680,"uuid":"456531433","full_name":"whame/tmux-modal","owner":"whame","description":"Execute complex tmux commands in just a few keystrokes with a modal mode that is designed to be efficient, easy to remember and comfortable","archived":false,"fork":false,"pushed_at":"2024-11-03T20:32:29.000Z","size":94,"stargazers_count":185,"open_issues_count":2,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-15T10:42:37.905Z","etag":null,"topics":["bindings","key","modal","plugin","tmux","vim"],"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/whame.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":"2022-02-07T14:06:34.000Z","updated_at":"2024-11-08T22:10:05.000Z","dependencies_parsed_at":"2023-02-01T00:15:30.659Z","dependency_job_id":"acd28b5e-9da3-4680-b0f7-1bae7a1883d9","html_url":"https://github.com/whame/tmux-modal","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whame%2Ftmux-modal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whame%2Ftmux-modal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whame%2Ftmux-modal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whame%2Ftmux-modal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/whame","download_url":"https://codeload.github.com/whame/tmux-modal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253144872,"owners_count":21861139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["bindings","key","modal","plugin","tmux","vim"],"created_at":"2024-08-03T04:00:50.434Z","updated_at":"2025-05-08T20:31:54.249Z","avatar_url":"https://github.com/whame.png","language":"Shell","funding_links":[],"categories":["Shell","Plugins"],"sub_categories":[],"readme":"tmux-modal\n==========\n\nExecute complex tmux commands in just a few keystrokes. tmux-modal introduces a\nmodal mode (e.g. like in Vim text editor) in tmux that is designed to be\nefficient, easy to remember and comfortable.\n\n## Examples\n\nHit `M-m` (`Alt-m` in tmux terminology) first to enter the modal command mode.\nThe status bar will show `[=]` to indicate that we are now in the modal mode\n(hit `M-m` again to exit back to \"normal\" mode). Here are some quick examples\nwhat one can do with tmux-modal (see the [keybindings](#keybindings) for a\ncomplete list).\n\n**Navigation**\n\nEasily move between panes and windows:\n\n![navigation-demo](https://user-images.githubusercontent.com/9569246/152884650-0daa8e87-4eff-4f36-b4b4-b693c3bdef28.gif)\n\n- `w l` to select the right pane\n- `w j` to select the pane below\n- `w 1` to select window 1\n- `w o` to go back to other/last windows\n\n**Management**\n\nCreate and delete windows with a breeze. Split, delete, zoom, move and break\npanes and much more in just a few keystrokes:\n\n![management-gif](https://user-images.githubusercontent.com/9569246/152884665-781279cd-c615-44f7-aaa0-8826e72c558c.gif)\n\n- `w c` to create a new window\n- `w D` to  delete window\n- `w s k` to  split window pane right\n- `w s j` to  split window pane below\n- `w d` to delete a pane\n- `w z` to zoom in/out of a pane\n\n**Sticky commands**\n\nUse sticky commands to do more, repeatedly. Sticky commands enters a _specific_\nmodal mode with specialized keybindings (see [keybindings](#keybindings) for a\nmore detailed explanation and a full list of available commands).\n\n![sticky-window-gif](https://user-images.githubusercontent.com/9569246/152884680-79e0dcd1-7d72-4120-9fab-44f9e5e211ae.gif)\n\nHit `w w` to enter sticky window command:\n\n- `s j` to split window pane below\n- `k` to select the above pane\n- `d` to delete a pane\n- `c` to create window\n- `0` to select window 0\n\nHit `w r` to enter sticky resize window command:\n\n![sticky-resize-gif](https://user-images.githubusercontent.com/9569246/152884687-29d6fff8-122e-4fa7-aeab-cc4d5ef1b198.gif)\n\n- `k` to resize the window pane one step upwards\n- `l` to resize the window pane one step to the right\n- `J` to resize the window pane multiple steps downwards\n- `H` to resize the window pane multiple steps to the left\n\n## Install\n\n### Tmux Plugin Manager\n\nUsing [Tmux Plugin Manager](https://github.com/tmux-plugins/tpm) is the\nrecommended way to install tmux-modal. Just add it as a plugin in your\n`~/.tmux.conf`:\n\n```\nset -g @plugin 'whame/tmux-modal'\n```\n\nThen hit `prefix` + `I` to install it (see the documentaion for Tmux Plugin\nManager for more details).\n\n### Manually\n\nYou can also clone and manually install tmux-modal. Put this at the end of your\n`~/.tmux.conf`:\n\n```\nrun /path/to/cloned/tmux-modal/tmux-modal.tmux\n```\n\nNote however that in this case you have to manually sync the cloned repository\nin order to get bug fixes, new features etc.\n\n## Keybindings\n\nThe following are the default keybindings of tmux-modal. (Note that these are\ncustomizable, as well as the command executed for each! See option\n[`@modal-keybindings-conf`](#custom-keybindings) and\n[`@modal-commands-conf`](#custom-commands), respectively.)\n\n### Main\n\n| Keybinding | Description                         | tmux Command     |\n|------------|-------------------------------------|------------------|\n| `M-m`      | Enter modal command mode.           | -                |\n| `M-m`      | Exit modal command mode.            | -                |\n| `y`        | Paste buffer (e.g. from copy mode). | `paste-buffer`   |\n| `c`        | Enter copy-mode.                    | `copy-mode`      |\n| `q`        | Quit sticky command.                | -                |\n| `:`        | Open tmux command mode.             | `command-prompt` |\n\n### Window\n\n| Keybinding | Description                                                 | tmux Command                                       |\n|------------|-------------------------------------------------------------|----------------------------------------------------|\n| `w w`      | Enter sticky window command mode.                           | -                                                  |\n| `w 0`      | Go to window 0. This is an alias for `g w 0`.               | `select-window -t :0`                              |\n| `w 1`      | Go to window 1. This is an alias for `g w 1`.               | `select-window -t :1`                              |\n| `w 2`      | Go to window 2. This is an alias for `g w 2`.               | `select-window -t :2`                              |\n| `w 3`      | Go to window 3. This is an alias for `g w 3`.               | `select-window -t :3`                              |\n| `w 4`      | Go to window 4. This is an alias for `g w 4`.               | `select-window -t :4`                              |\n| `w 5`      | Go to window 5. This is an alias for `g w 5`.               | `select-window -t :5`                              |\n| `w 6`      | Go to window 6. This is an alias for `g w 6`.               | `select-window -t :6`                              |\n| `w 7`      | Go to window 7. This is an alias for `g w 7`.               | `select-window -t :7`                              |\n| `w 8`      | Go to window 8. This is an alias for `g w 8`.               | `select-window -t :8`                              |\n| `w 9`      | Go to window 9. This is an alias for `g w 9`.               | `select-window -t :9`                              |\n| `w t`      | Select window with tree view. This is an alias for `g w t`. | `choose-tree -Zw`                                  |\n| `w i`      | Select window with index. This is an alias for `g w i`.     | `command-prompt -p index \"select-window -t ':%%'\"` |\n| `w h`      | Select left pane.                                           | `select-pane -L`                                   |\n| `w l`      | Select right pane.                                          | `select-pane -R`                                   |\n| `w k`      | Select above pane.                                          | `select-pane -U`                                   |\n| `w j`      | Select below pane.                                          | `select-pane -D`                                   |\n| `w d`      | Delete window pane.                                         | `kill-pane`                                        |\n| `w H`      | Select previous window. This is an alias for `g w h`.       | `select-window -t :-`                              |\n| `w L`      | Select next window. This is an alias for `g w l`.           | `select-window -t :+`                              |\n| `w D`      | Delete window.                                              | `kill-window`                                      |\n| `w c`      | Create new window.                                          | `new-window`                                       |\n| `w o`      | Select other/last window.                                   | `last-window`                                      |\n| `w z`      | Zoom pane.                                                  | `resize-pane -Z`                                   |\n| `w b`      | Break pane into a new window.                               | `break-pane`                                       |\n| `w n`      | Display pane numbers.                                       | `display-panes`                                    |\n| `w ,`      | Rename window.                                              | `command-prompt -I \"#W\" \"rename-window -- '%%'\"`   |\n| `w s l`    | Split window pane right.                                    | `split-window -h`                                  |\n| `w s j`    | Split window pane down.                                     | `split-window`                                     |\n| `w m k`    | Move window pane up.                                        | `swap-pane -U`                                     |\n| `w m j`    | Move window pane down.                                      | `swap-pane -D`                                     |\n| `w a 1`    | Arrange window to layout 1.                                 | `select-layout even-horizontal`                    |\n| `w a 2`    | Arrange window to layout 2.                                 | `select-layout even-vertical`                      |\n| `w a 3`    | Arrange window to layout 3.                                 | `select-layout main-horizontal`                    |\n| `w a 4`    | Arrange window to layout 4.                                 | `select-layout main-vertical`                      |\n\nNote that the sticky window command (`w w`) allows one to execute all of the\nabove commands in the table but without the initial `w`. For example, after\nhitting `w w`, `s l` splits the window pane to the right, `d` deletes the window\npane, `h` selects the left pane and so on (`q` exits the sticky command). Also\nsee the option [`@modal-always-sticky`](#always-sticky-command) if you instead\nalways want to use the sticky command version (with only hitting `w` once).\n\n#### Resize\n\n| Keybinding | Description                        | tmux Command |\n|------------|------------------------------------|--------------|\n| `w r`      | Enter sticky resize window command | -            |\n\nWhen in sticky resize window command, the following resizes the window (as\nusual, `q` exits the sticky command).\n\n| Keybinding | Description                                          | tmux Command       |\n|------------|------------------------------------------------------|--------------------|\n| `h`        | Resizes the window pane one step to the left.        | `resize-pane -L`   |\n| `l`        | Resizes the window pane one step to the right.       | `resize-pane -R`   |\n| `j`        | Resizes the window pane one step downwards.          | `resize-pane -D`   |\n| `k`        | Resizes the window pane one step upwards.            | `resize-pane -U`   |\n| `H`        | Resizes the window pane multiple steps to the left.  | `resize-pane -L 5` |\n| `L`        | Resizes the window pane multiple steps to the right. | `resize-pane -R 5` |\n| `J`        | Resizes the window pane multiple steps downwards.    | `resize-pane -D 5` |\n| `K`        | Resizes the window pane multiple steps upwards.      | `resize-pane -U 5` |\n\n### Session\n\n| Keybinding | Description                                                  | tmux Command                                   |\n|------------|--------------------------------------------------------------|------------------------------------------------|\n| `s d`      | Detach session.                                              | `detach-client`                                |\n| `s h`      | Select previous session. This is an alias for `g s h`.       | `switch-client -p`                             |\n| `s l`      | Select next session. This is an alias for `g s l`.           | `switch-client -n`                             |\n| `s t`      | Select session with tree view. This is an alias for `g s t`. | `choose-tree -Zs`                              |\n| `s D`      | Delete session.                                              | `kill-session`                                 |\n| `s ,`      | Rename session.                                              | `command-prompt -I \"#S\" \"rename-session '%%'\"` |\n\n\n### Go to\n\n#### Window\n\n| Keybinding | Description                  | tmux Command                                       |\n|------------|------------------------------|----------------------------------------------------|\n| `g w 0`    | Go to window 0.              | `select-window -t :0`                              |\n| `g w 1`    | Go to window 1.              | `select-window -t :1`                              |\n| `g w 2`    | Go to window 2.              | `select-window -t :2`                              |\n| `g w 3`    | Go to window 3.              | `select-window -t :3`                              |\n| `g w 4`    | Go to window 4.              | `select-window -t :4`                              |\n| `g w 5`    | Go to window 5.              | `select-window -t :5`                              |\n| `g w 6`    | Go to window 6.              | `select-window -t :6`                              |\n| `g w 7`    | Go to window 7.              | `select-window -t :7`                              |\n| `g w 8`    | Go to window 8.              | `select-window -t :8`                              |\n| `g w 9`    | Go to window 9.              | `select-window -t :9`                              |\n| `g w t`    | Go to window with tree view. | `choose-tree -Zw`                                  |\n| `g w i`    | Go to window with index.     | `command-prompt -p index \"select-window -t ':%%'\"` |\n| `g w h`    | Go to previous window.       | `select-window -t :-`                              |\n| `g w l`    | Go to next window.           | `select-window -t :+`                              |\n| `g w o`    | Go to other/last window.     | `last-window`                                      |\n\n#### Session\n\n| Keybinding | Description                   | tmux Command       |\n|------------|-------------------------------|--------------------|\n| `g s h`    | Go to previous session.       | `switch-client -p` |\n| `g s l`    | Go to next session.           | `switch-client -n` |\n| `g s t`    | Go to session with tree view. | `choose-tree -Zs`  |\n\n## Customization\n\n### Custom keybindings\n\nThe option `@modal-keybindings-conf` can be set to load custom keybindings. The\nfile [`keybindings.conf`](keybindings.conf) shows the default keybindings and\ncan be used as a template. Thus, copy the file and modify it to your liking, and\nfinally set this in your `.tmux.conf` to load them:\n\n```\nset -g @modal-keybindings-conf /path/to/my-tmux-modal-keybindings.conf\n```\n\n### Custom commands\n\nThe option `@modal-commands-conf` can be set to load custom commands that will\nbe executed for the keybindings. The file [`commands.conf`](commands.conf) shows\nthe default commands and can be used as a template. Thus, copy the file and\nmodify it to your liking, and finally set this in your `.tmux.conf` to load\nthem:\n\n```\nset -g @modal-commands-conf /path/to/my-tmux-modal-commands.conf\n```\n\n### Start with modal command mode\n\nThe option `@modal-on-start` can be used to automatically enter the modal\ncommand mode on a new tmux session. If you always want to start a new session\nwith the modal command mode, add the following to `.tmux.conf`:\n\n```\nset -g @modal-on-start on\n```\n\n### Always sticky command\n\nThe option `@modal-always-sticky` can be specified to always use the sticky\nversion instead of manually entering the sticky command first (e.g. `w w` for\nsticky window command):\n\n```\nset -g @modal-always-sticky on\n```\n\nFor example, with this in `.tmux.conf`, one only has to press `w` once and the\nsticky window command mode will be entered directly. That is, after hitting `w`\nonce, you can now directly use `h`, `j`, `k` and `l` to select the window panes\n(or any other window commands). Don't forget to exit the sticky command with\n`q`.\n\n### Show command keys in status bar\n\nThe option `@modal-show-cmd-keys` can be set in `.tmux.conf` to give immediate\nfeedback in the status bar during tmux-modal command sequences:\n\n```\nset -g @modal-show-cmd-keys on\n```\n\nThe left status bar will now update to match the tmux-modal command currently in\nuse. For example, if you press `w` the status bar will change from the modal\ncommand icon `[=]` to `[w]` (the window command). If you now further press `s`,\nit will update to `[ws]` to signify the split window command sequence and so on.\n\n### Set custom status bar modal mode icon\n\nThe option `@modal-cmd-icon` can be used to specify any string, which will be\nthe left status bar icon to indicate that modal mode is in use. For example, to\nuse a circle as icon (note the padding at the beginning for a more aesthetically\ncentering in the status bar):\n\n```\nset -g @modal-cmd-icon \" 🟢\"\n```\n\n### Yes/no prompt\n\n**DEPRECATED**\n\nThis option is deprecated due to option\n[`@modal-commands-conf`](#custom-commands) and will be removed soon. To keep the\nold behavior, use option [`@modal-commands-conf`](#custom-commands) instead. For\nexample:\n\n```\ndiff --git a/commands.conf b/commands.conf\nindex 1859fcb..ec4f65e 100644\n--- a/commands.conf\n+++ b/commands.conf\n@@ -82,7 +82,7 @@ CMD_WIN_PANE_UP='select-pane -U'\n CMD_WIN_PANE_DOWN='select-pane -D'\n\n ## Delete window pane.\n-CMD_WIN_PANE_DEL='kill-pane'\n+CMD_WIN_PANE_DEL='confirm-before -p \"kill-pane #P? (y/n)\" kill-pane'\n\n ## Select previous window (window command alias for CMD_GOTO_WIN_PREV).\n CMD_WIN_PREV='select-window -t :-'\n@@ -91,7 +91,7 @@ CMD_WIN_PREV='select-window -t :-'\n CMD_WIN_NEXT='select-window -t :+'\n\n ## Delete window.\n-CMD_WIN_DEL='kill-window'\n+CMD_WIN_DEL='confirm-before -p \"kill-window #W? (y/n)\" kill-window'\n\n ## Create new window.\n CMD_WIN_CREATE='new-window'\n@@ -183,7 +183,7 @@ CMD_SESS_NEXT='switch-client -n'\n CMD_SESS_TREE='choose-tree -Zs'\n\n ## Delete session.\n-CMD_SESS_DEL='kill-session'\n+CMD_SESS_DEL='confirm-before -p \"kill-session #S? (y/n)\" kill-session'\n\n # \"Go to\" command prefix.\n```\n\n---\n\n_Some commands might be too \"dangerous\" to execute directly, for example `w d`\n(`kill-pane`) or `w D` (`kill-window`). The option `@modal-yesno-cmd` can\ntherefore be used to ask for confirmation before executing the commands (to\nmimic the default tmux behavior). If you want a yes/no prompt before executing\nthese commands, put this in `.tmux.conf`:_\n\n```\nset -g @modal-yesno-cmd on\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhame%2Ftmux-modal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhame%2Ftmux-modal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhame%2Ftmux-modal/lists"}