{"id":15114298,"url":"https://github.com/MLFlexer/modal.wezterm","last_synced_at":"2025-09-27T18:30:42.584Z","repository":{"id":233930708,"uuid":"788045678","full_name":"MLFlexer/modal.wezterm","owner":"MLFlexer","description":"Vim-like modal keybindings for your terminal! ✌️","archived":false,"fork":false,"pushed_at":"2024-08-08T12:30:35.000Z","size":70,"stargazers_count":19,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-09-26T01:43:03.542Z","etag":null,"topics":["keybind","keybindings","modal","plugin","vim","wezterm"],"latest_commit_sha":null,"homepage":"","language":"Lua","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/MLFlexer.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":"2024-04-17T17:13:36.000Z","updated_at":"2024-09-26T00:27:25.000Z","dependencies_parsed_at":"2024-08-04T09:51:46.579Z","dependency_job_id":null,"html_url":"https://github.com/MLFlexer/modal.wezterm","commit_stats":null,"previous_names":["mlflexer/modal.wezterm"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLFlexer%2Fmodal.wezterm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLFlexer%2Fmodal.wezterm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLFlexer%2Fmodal.wezterm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MLFlexer%2Fmodal.wezterm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MLFlexer","download_url":"https://codeload.github.com/MLFlexer/modal.wezterm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234450839,"owners_count":18834586,"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":["keybind","keybindings","modal","plugin","vim","wezterm"],"created_at":"2024-09-26T01:41:11.240Z","updated_at":"2025-09-27T18:30:42.572Z","avatar_url":"https://github.com/MLFlexer.png","language":"Lua","readme":"# modal.wezterm\nVim-like modal keybindings for your terminal! ✌️\n\n## Overview\nAdd keybindings which operate with vim-like modal bindings to accelerate your workflow.\nThis plugin adds great opt-in default modes along with optional visual indicators and hints for the keybindings.\n\n#### Default Copy/Visual/Search mode\nImprovements to [Wezterms CopyMode](https://wezfurlong.org/wezterm/copymode.html) with vim keybindings\n![Demo of Copy/Search/Visual mode](https://github.com/MLFlexer/modal.wezterm/assets/75012728/08c2af5c-c75a-4764-bd63-729a91080f79)\n\n\n\n#### Default UI mode\n\n![Demo of UI mode](https://github.com/MLFlexer/modal.wezterm/assets/75012728/84e5860a-5659-43d9-af51-bb2942b005a6)\n\n## Default modes\nI have included some default modes which are opt-in as to improve performance for all users.\n\n### Copy mode, with Search and Visual submodes\n![Copy mode](https://github.com/MLFlexer/modal.wezterm/assets/75012728/d11d088c-f99a-464f-8de6-2a447da1e57a)\n![Visual mode](https://github.com/MLFlexer/modal.wezterm/assets/75012728/b8c63098-f8e3-481e-8881-b617d6b87a80)\n![Search mode](https://github.com/MLFlexer/modal.wezterm/assets/75012728/ee8a9881-2c7f-499f-ba66-f55f81360869)\n\n### UI mode\nUI mode has vim-like bindings to navigate and modify panes, tabs and other UI elements.\n![UI mode](https://github.com/MLFlexer/modal.wezterm/assets/75012728/07545d3d-2f94-44df-8f02-cb9ff0ee6d0a)\n\n### Scroll mode\nIn scroll mode you can scroll with familiar vim bindings.\n![Scroll mode](https://github.com/MLFlexer/modal.wezterm/assets/75012728/52e792dd-580d-4bea-a31f-e5f589212217)\n\n## Setup\nIt is recommended to do the setup with some [Customization](#Customization). However if you just want to try it out you can follow the [Preset](#Preset)\n### Preset\nAdd the following to the bottom of your config:\n```lua\nlocal wezterm = require(\"wezterm\")\nlocal modal = wezterm.plugin.require(\"https://github.com/MLFlexer/modal.wezterm\")\nmodal.apply_to_config(config)\nmodal.set_default_keys(config)\n```\nThis will add the keybindings to enter and exit modes:\n* `ALT-u` to enter UI mode from normal mode\n* `ALT-c` to enter Copy mode from normal mode\n* `v` to enter visual mode from Copy mode\n* `/` to enter search mode from Copy mode\n* `ALT-n` to enter Scroll mode from normal mode\n* `esc` or `CTRL-c` to leave current non-normal mode\n\nCheckout the [keybinding descriptions](/defaults/keybinds.md)\n\n### Customization\n1. Require the plugin:\n```lua\nlocal wezterm = require(\"wezterm\")\nlocal modal = wezterm.plugin.require(\"https://github.com/MLFlexer/modal.wezterm\")\n```\n2. Add your own mode\n\n*There are more examples of key tables and status texts with and without hints in the `/defaults` directory.*\n```lua\n-- example key table\nlocal key_table = {\n  { key = \"Escape\", action = modal.exit_mode(\"mode_name\") },\n  { key = \"c\", mods = \"CTRL\", action = modal.exit_mode(\"mode_name\") },\n  { key = \"z\", action = wezterm.action.TogglePaneZoomState },\n}\n-- example right status text\nlocal status_text = wezterm.format({\n  { Attribute = { Intensity = \"Bold\" } },\n  { Foreground = { Color = \"Red\" } },\n  { Text = wezterm.nerdfonts.ple_left_half_circle_thick },\n  { Foreground = { Color = \"Black\" } },\n  { Background = { Color = \"Red\" } },\n  { Text = \"MODE NAME  \" },\n})\nmodal.add_mode(\"mode_name\", key_table, status_text)\n```\n3. Add you keybind to enter the mode\n```lua\nconfig.keys = {\n  -- ...\n  -- your other keybindings\n  {\n    key = \"m\",\n    mods = \"ALT\",\n    action = activate_mode(\"mode_name\"),\n  }\n}\n```\n4. Add the modes to your config\n```lua\nconfig.key_tables = modal.key_tables\n```\n5. Change right status text when entering/leaving mode\n```lua\nwezterm.on(\"update-right-status\", function(window, _)\n  modal.set_right_status(window)\nend)\n```\n\n## Configuration\n### Enabling default modes\nIf you want to enable a default mode, then you can add the following:\n```lua\nmodal.enable_defaults(\"https://github.com/MLFlexer/modal.wezterm\")\n-- \"ui_mode\" can be replaced by any filename from the /defaults directory\nlocal key_table = require(\"ui_mode\").key_table\n\nlocal icons = {\n  left_seperator = wezterm.nerdfonts.ple_left_half_circle_thick,\n  key_hint_seperator = \" | \",\n  mod_seperator = \"-\",\n}\nlocal hint_colors = {\n  key_hint_seperator = \"Yellow\",\n  key = \"Green\",\n  hint = \"Red\",\n  bg = \"Black\",\n  left_bg = \"Gray\",\n}\nlocal mode_colors = { bg = \"Red\", fg = \"Black\" }\nlocal status_text = require(\"ui_mode\").get_hint_status_text(icons, hint_colors, mode_colors)\n\nmodal.add_mode(\"UI\", key_table, status_text)\n\nconfig.keys = {\n  -- ...\n  -- your other keybindings\n  {\n    key = \"u\",\n    mods = \"ALT\",\n    action = activate_mode(\"UI\"),\n  }\n}\nconfig.key_tables = modal.key_tables\n```\nCheckout the specific lua files to see the keybindings and what functionality each mode exports\n\n### Adding custom right status text\nTo add a custom right status you can use the [wezterm.format()](https://wezfurlong.org/wezterm/config/lua/wezterm/format.html) function to create a formatted string. You can then add it as an argument when you add your mode:\n```lua\nlocal custom_status = wezterm.format({\n  { Attribute = { Intensity = \"Bold\" } },\n  { Foreground = { Color = bg } },\n  { Text = wezterm.nerdfonts.ple_left_half_circle_thick },\n  { Foreground = { Color = fg } },\n  { Background = { Color = bg } },\n  { Text = \"Some custom text  \" },\n})\nmodal.add_mode(\"mode_name\", key_table, custom_status)\n```\nYou should then add the text to your right status by following the steps in the next paragraph\n### Update right status on mode change\n#### *Recommended:* Using enter and exit events\nYou can use the `modal.enter` and `modal.exit` events to set the right status:\n```lua\nwezterm.on(\"modal.enter\", function(name, window, pane)\n  modal.set_right_status(window, name)\n  modal.set_window_title(pane, name)\nend)\n\nwezterm.on(\"modal.exit\", function(name, window, pane)\n  window:set_right_status(\"NOT IN A MODE\")\n  modal.reset_window_title(pane)\nend)\n```\n#### Using the wezterm.on(\"update-right-status\", ...) event\nAlternatively you can show some other text in the right status by making a simple if statement in your `wezterm.on` function:\n```lua\nwezterm.on(\"update-right-status\", function(window, _)\n  if modal.get_mode(window) then -- is nil if you are not in a mode\n    modal.set_right_status(window)\n  else\n    -- your other status\n  end\nend)\n```\n\n## Credits\nThanks to [github.com/twilsoft/wezmode](https://github.com/twilsoft/wezmode) for the inspiration to make this plugin. I have created this plugin as a lua alternative to wezmode, as I wanted to extend wezmode, but with lua instead of typescript.\n","funding_links":[],"categories":["Keybinding"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMLFlexer%2Fmodal.wezterm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMLFlexer%2Fmodal.wezterm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMLFlexer%2Fmodal.wezterm/lists"}