{"id":13412510,"url":"https://github.com/nikvdp/neomux","last_synced_at":"2026-01-12T14:45:51.309Z","repository":{"id":42614151,"uuid":"191072540","full_name":"nikvdp/neomux","owner":"nikvdp","description":"Control Neovim from shells running inside Neovim.","archived":false,"fork":false,"pushed_at":"2023-04-17T10:32:14.000Z","size":16606,"stargazers_count":343,"open_issues_count":2,"forks_count":10,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-07-31T20:50:59.672Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Vim Script","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/nikvdp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","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},"funding":{"ko_fi":"arghzero","github":"nikvdp"}},"created_at":"2019-06-10T01:00:12.000Z","updated_at":"2024-07-26T17:43:05.000Z","dependencies_parsed_at":"2024-01-03T03:30:00.902Z","dependency_job_id":"bc133fb7-ab30-472d-a465-e68ce65dc7f2","html_url":"https://github.com/nikvdp/neomux","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikvdp%2Fneomux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikvdp%2Fneomux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikvdp%2Fneomux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikvdp%2Fneomux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nikvdp","download_url":"https://codeload.github.com/nikvdp/neomux/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221495304,"owners_count":16832455,"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":[],"created_at":"2024-07-30T20:01:25.528Z","updated_at":"2026-01-12T14:45:46.271Z","avatar_url":"https://github.com/nikvdp.png","language":"Vim Script","funding_links":["https://ko-fi.com/arghzero","https://github.com/sponsors/nikvdp"],"categories":["Terminal Integration","Vim Script","Vim script"],"sub_categories":["Cursorline","CSV Files"],"readme":"# Neomux - control Neovim from shells running inside Neovim.\n\nNeomux packages and wraps [neovim-remote][neovim-remote] goodness into your\nneovim terminals so you can work with neovim's `:term` emulator in some\ninteresting new ways. Here's some of the things it lets you do:\n\n- Pipe commands from the shell into a neovim window (and back to the shell) via stdin/stdout\n- Easily jump to any neovim windows with 3 keystrokes, even when you have lots of\n  splits and windows in-between (no more \u003cC-w\u003el\u003cC-w\u003el\u003cC-w\u003el to get to the 3rd\n  window on the right)\n- Get and set the contents of vim registers from the command line via stdin/stdout.\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"75%\" src=\"https://nikvdp.com/images/neomux-2-window-numbers.gif\"\u003e\n\u003c/p\u003e\n\n\n# Quickstart\n\nInstall neomux, start a neomux shell with `:Neomux` (mapped to `\u003cLeader\u003esh` by\ndefault), and use `vw \u003cwin_num\u003e \u003cfile\u003e` and friends to open files in vim\nwindows from the shell.\n\nFor more info see the [tutorial](#tutorial).\n\n# Installation\n\n1. Install neovim. \n2. Install this plugin into neovim via your favorite plugin manager\n   ([vim-plug][vim-plug] is a good place to start)\n3. (Optional, for speed) install [neovim-remote][neovim-remote].\n\n\n# Usage\n\nNeomux is meant to replace tools like tmux -- instead of relying on tmux or a\nfancy tabbed terminal emulator to run multiple shell windows (many of which, if\nyou're anything like me, have instances of nvim running inside of them) you can\ninstead just have one neovim session open and run your shells inside neovim.\nVim has great tab and window splitting support, so you can rely on (neo)vim's\nmature window and tab management workflow to make flipping between the files\nyou're editing and your shell(s) painless. Files and shells are both\nfirst-class citizens, and all the tools you need to pass data between neovim\nand your shell are included.\n\n## Basics \nYou can start a neomux shell in a neovim window with `:Neomux` or with\nthe mapping `\u003cLeader\u003esh`.\n\n**Terminals started via other methods (e.g. `:term`) will not have neomux functionality!**\n\n\u003e **NOTE:**\n\u003e\n\u003e Neomux will automatically tell the shell to use your current neovim session as\n\u003e the default editor via the `$EDITOR` shell variable. This means that tools like\n\u003e `git` and `kubectl` will open files in your existing neovim session. Make sure you \n\u003e use neovim's `:bd` (buffer delete) command when you are finished editing your\n\u003e files to notify the calling program you are done -- this is equivalent to\n\u003e closing a non-neomux editor. \n\n\n\n## Window navigation\n\nAfter installing neovim you will notice that every window in vim now shows a numeric\nidentifier in it's status bar that looks like this: \n\n``` \n∥ W:1 ∥\n```\n\nThis number identifies every window on the screen and is how you refer to\nindividual windows in neomux.\n\n## Key bindings\n\nNeomux adds some new key mappings to make working with windows easier.  The\ndefault keybindings can be customized from your `vimrc` / `init.vim`, see\n[customization](#customization) for more info. \n\nIn the default settings some commands are accessed via the `\u003cLeader\u003e` key (`\\`\non a vanilla neovim install):\n\n- `\u003cLeader\u003esh` - Start a new neomux term in the current window.\n- `\u003cC-w\u003et` - Start a new neomux term above the current window (`:split`)\n- `\u003cC-w\u003eT` - Start a new neomux term to the left of the current window (`:vsplit`)\n- `\u003cC-w\u003e[1-9]` - move the cursor directly to the window specified (e.g.\n  `\u003cC-w\u003e3` would move the cursor to window 3)\n- `\u003cLeader\u003es[1-9]` - swap the current window with another window. (e.g.\n  `\u003cLeader\u003es3` would make your current window switch places with window #3)\n- `\u003cC-s\u003e` - Exit insert mode while in a neomux shell. This is just an alias for\n  `\u003cC-\\\u003e\u003cC-n\u003e` which is the default keymap to end terminal insert mode.\n- `\u003cLeader\u003esf` - size-fix. If you re-arrange windows neovim's terminal\n  sometimes doesn't automatically resize the terminal to match the new window's\n  size. This keymapping will cause the window to refresh and resize.\n- `\u003cLeader\u003eby` - yank buffer. Sometimes it's handy to be able to yank a buffer\n  and paste it into a new window (I often use this if I want to move a window\n  to a new tab). Yanked buffers can be pasted with `\u003cLeader\u003ebp`.\n- `\u003cLeader\u003ebp` - paste a previously yanked buffer into a window.\n\n# Tutorial\n\nAn extended version of this tutorial is available in the [introducing\nneomux][neomux-blog-post] blog post.  All neomux terminals come pre-loaded with\nsome handy new shell commands.\n\n### Opening files in new windows: `s`, `vs`, and (kind of) `t`\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"75%\" src=\"https://nikvdp.com/images/neomux-1-new-windows.gif\"\u003e\n\u003c/p\u003e\n\nThe simplest of the new neomux shell commands are `s`, `vs` and `t`. These\nstand for `s`plit, `v`ertical-`s`plit, and `t`ab, and are straightforward to use.\n\nIf you have a neomux shell open and wanted to open a file you were looking at \nin a *new* window, you would simply do:\n\n``` sh\ns \u003csome-file\u003e\n```\n\nSimilarly, `vs \u003csome-file\u003e`, and `t \u003csome-file\u003e` would open `\u003csome-file\u003e` in \na vertical split, or a new tab, respectively.\n\n\n### Working with windows by window-number: `vw` and `vwp`\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"75%\" src=\"https://nikvdp.com/images/neomux-2-window-numbers.gif\"\u003e\n\u003c/p\u003e\n\n\u003c!--\n\u003cdiv style=\"text-align: center;\"\u003e \u003cscript id=\"asciicast-251096\" src=\"https://asciinema.org/a/251096.js\" async\u003e\u003c/script\u003e \u003c/div\u003e\n--\u003e\n\n\nOne of the most commonly used neomux commands is `vw` (vim-window), it allows\nyou to open a file in an *already open* window.\n\nFor example if you have 3 windows open in your current nvim session/tab and you \nwanted to open a file named `my-file.txt` in the 2nd window you'd do:\n\n``` sh\nvw 2 my-file.txt\n```\n\nYou can also use pass `-` as the filename to stream the contents of `stdin`\ninto a vim-window, which when combined with the shell's `|` characters makes\nfor some interesting possibilities. \n\nThe `vwp` (vim-window-print) command does the reverse of the `vw` command. It\ntakes the contents of any vim window and streams it out to standard out. When\nyou combine this with your shell's [process substition][process-substition]\nfunctionality, you can do some interesting things such as interactively working\non a bash script without having to first write it to a file. Check out vid above\nfor more details\n\n### Copying/yanking and pasting text to and from neomux\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"75%\" src=\"https://nikvdp.com/images/neomux-3-registers.gif\"\u003e\n\u003c/p\u003e\n\n\nNeomux comes with two helpers for working with vim's registers to copy and paste\ntext: `vc` and `vp`, which stand for vim-copy and vim-paste respectively.\n\nWith these, you can manipulate the contents of vim's yank ring and registers\nfrom the command line. If you're not familiar with vim's register system, I\nrecommend first checking out [vim's documentation on the\ntopic][vim-registers-docs] and/or [this tutorial][vim-registers-tut].\n\nBoth `vc` and `vp`, work on the default register (`@\"`) if no register is\nspecified.  To work with a specific register just pass it as the first cmd-line\nparam. For example, to work with register `a` (`@a`), you would use `vw a`, and\n`vp a`. \n\nTo put data in a register pipe it in via stdin:\n\n``` sh\n$ echo \"This is what's in register a.\" | vc a\n```\n\nAnd get it out with `vp`:\n\n``` sh\n$ vp a\nThis is what's in register a. \n```\n\nAll vim register semantics are preserved, so you can append to the contents of a \nregister by capitalizing the register name:\n\n``` sh\n$ echo \" Appended to register a.\" | vc A\n$ vp a\nThis is what's in register a. Appended to register a.\n```\n\nSpecial registers such as `/` and `+` work just like any other register, so\nyou could even use these as a roundabout way to replace `pbpaste` / `xsel` by\nusing `vp +` (although this is silly since at the end of the day neovim will\nprobably call those same tools to retrieve the clipboard). \n\n# CLI helper reference\n\nWhen you start a neomux shell some new helper commands will be available to you\nto streamline working with neovim.\n\n\n- ### `vw \u003cwin_num\u003e \u003cfile\u003e` \n\n  Open `\u003cfile\u003e` in vim window number `\u003cwin_num\u003e`, where `\u003cwin_num\u003e` is a number\n  between 1 and 9. For example:\n\n  ``` bash\n  vw 2 ~/.config/nvim/init.vim \n  ```\n\n  Would open your neovim config in window 2.\n\n  You can also pipe shell commands into neovim windows by using `-` as the\n  filename. The below command would fill window 2 with the list of files in the\n  shell's working directory:\n\n  ``` bash\n  ls | vw 2 -\n  ```\n- ### `vws \u003cwin_num\u003e \u003cfile\u003e` \n  Like `vw`, but perform a horizontal split on `\u003cwin_num\u003e` before opening `\u003cfile\u003e` there.\n\n- ### `vc [register]` \n  copy data into a vim register (`@\"` if no register specified). Example:\n\n  ``` bash\n  ls | vc a\n  ```\n\n  Would put the listing of files in the shell's working directory into vim register `a`, \n  which you could then paste in vim by doing e.g. `\"aP`\n\n- ### `vp [register]`\n  paste data from a vim register (`@\"` if no register specified).\n- ### `e \u003cfile\u003e`\n  Open  `\u003cfile\u003e`  in current window.\n- ### `s \u003cfile\u003e`\n  Open `\u003cfile\u003e` in a horizontal split.\n- ### `vs \u003cfile\u003e`\n  Open `\u003cfile\u003e` in a vertical split.\n- ### `t \u003cfile\u003e`\n  Open `\u003cfile\u003e` in a new tab.\n- ### `vcd \u003cpath\u003e`\n  Switch neovim's working dir to `\u003cpath\u003e`.\n- ### `vpwd`\n  Print neovim's working dir. Useful in combination with `cd` (eg `cd\n  \"$(vpwd)\"`) to quickly cd to neovim's working dir\n\n\n\u003c!--\n# Cookbook\n\n- A useful pattern is to combine `vw`, `vp`, and `xargs` to do\n  operations over sets of files. For example, if you wanted to delete all files in a folder \n  except for file `b`, you could do:\n\n  ``` bash\n  ls | vw 2 -\n  ...edit the file list in nvim and delete `b`...\n  ...select all files and yank to the `@\"` register with `ggVGy`...\n  vp | xargs rm  # \n  ```\n--\u003e\n\n\n# Customization\n\nNeomux comes with a sane set of defaults, but it's meant to get out of your\nway, so much of it's behavior is configurable. \n\nConfigure neomux by setting any of these variables in your `.vimrc` / `init.vim`:\n\n\n### Key bindings: \n\n- `g:neomux_start_term_map` - Default: `\u003cLeader\u003esh`. This map controls what\n  keys start a new Neomux term in the current window.\n- `g:neomux_start_term_split_map` - Default: `\u003cC-w\u003et`. This map controls what\n  keys start a Neomux term in a `:split` window.\n- `g:neomux_start_term_vsplit_map` - Default: `\u003cC-w\u003eT`. This map controls what keys\n  start a Neomux term in a `:vsplit` window.\n- `g:neomux_winjump_map_prefix` - Default: `\u003cC-w\u003e`. In Neomux you\n  can jump to any open window by hitting `\u003cC-w\u003e\u003cwin_num\u003e` (e.g. `\u003cC-w\u003e2` jumps to\n  window 2. Change this if you want to jump to a different window with a\n  different mapping. \n  \n  \u003e **NOTE:** this is a prefix map, so whatever key you specify will\n  \u003e have 9 new mappings generated, one for each window. E.g. if you change this to\n  \u003e `\u003cC-b\u003e`, you would hit `\u003cC-b\u003e2` to move to window 2.\n- `g:neomux_winswap_map_prefix` -  Default: `\u003cLeader\u003es`. You can swap\n  the current window with any other window by hitting `\u003cLeader\u003es\u003cwin_num\u003e`.\n  Change this if you don't want to use `\u003cLeader\u003es` for this map.\n\n  \u003e **NOTE:** like `g:neomux_winjump_map_prefix`, this is a prefix map, so if you change it to\n  \u003e `\u003cLeader\u003eb` it would create 9 new mappings, and you'd swap the current window\n  \u003e with window #2 with `\u003cLeader\u003eb2`.\n- `g:neomux_yank_buffer_map` - Default: `\u003cLeader\u003eby`. Yank a buffer to be pasted later.\n- `g:neomux_paste_buffer_map` - Default: `\u003cLeader\u003ebp`. Paste a previously yanked buffer into the current window.\n- `g:neomux_term_sizefix_map` - Default: `\u003cLeader\u003esf`. Fix a neomux term window that is the wrong size\n- `g:neomux_exit_term_mode_map` - Default: `\u003cC-s\u003e`. Get out of insert mode when inside a neomux terminal window.\n\n### Other config\n\n- `g:neomux_default_shell` - Default: the value of your system's `$SHELL` env\n  var. Neomux starts with the default shell for your user, but if you want to\n  override this to force Neomux terminals to run bash/zsh/your-preferred-shell,\n  set this var in your `.vimrc`/`init.vim`. E.g., if you want Neomux shells to\n  start zsh, you would put `let g:neomux_default_shell = \"zsh\"` in your\n  `init.vim`.\n- `g:neomux_win_num_status` - Default: `∥ W:[%{WindowNumber()}] ∥`. By default\n  Neomux adds decorations that look like `∥ W:1 ∥` to each window. If you'd like\n  to customize this, set this variable to a different value. `%{WindowNumber()}`\n  will be replaced by the window number itself. \n\n  If you have [airline](https://github.com/vim-airline/vim-airline) installed\n  neomux will attempt to add it to your airline. If this doesn't work for you\n  please leave an issue! **However, be sure to configure your plugin manager to\n  load neomux *after* the airline plugin.**\n\n- `g:neomux_dont_fix_term_ctrlw_map` - By default you can't get out of a neovim\n  terminal window with `\u003cC-w\u003e` the way you can from a normal vim window. Neomux\n  modifies the default mappings so that `\u003cC-w\u003e` works the same way in a terminal\n  window as it does a normal window. Neomux includes a `NeomuxSendCtrlW()` helper\n  function which you can use to send `\u003cC-w\u003e` to a terminal (`:call\n  NeomuxSendCtrlW()`), however if you find yourself needing to use `\u003cC-w\u003e` often,\n  you can restore neovim's default settings by setting\n  `g:neomux_dont_fix_term_ctrlw_map` to `1`.\n\n- `g:neomux_no_exit_term_map` - By default neomux adds a new mapping\n  (`g:neomux_exit_term_mode_map`) to easily exit insert mode in a terminal\n  window. If you don't want this mapping to be set at all and would like to use\n  neovim's default `\u003cC-\\\u003e\u003cC-n\u003e`, you can disable it by setting\n  `g:neomux_no_exit_term_map` to `1`.\n\n- `g:neomux_hitenter_fix` - There is \n  [a neovim issue](https://github.com/neovim/neovim/issues/20380) when using\n  `cmdheight=0` that causes hit-enter confirmations in neovim when any of the\n  `g:neomux_start_term_*map` keys are executed. Until the upstream issue is\n  fixed, you can work around it by setting `g:neomux_hitenter_fix` to `1`.\n\n### Miscellanea / troubleshooting\n\n- If you want a simple way to send keys to a neomux terminal session you can do\n  so via the `NeomuxSend(keys)` function. \n\n- Neomux relies heavily on the excellent [neovim-remote][neovim-remote], and\n  includes amd64 binaries for neovim-remote for MacOS and Linux as they are the\n  most popular platforms. If you're on Windows or using another chipset (e.g.\n  Raspberry pi/ARM) you will need to install python and `pip` manually, and\n  then install neovim-remote via `pip install neovim-remote` before neomux will\n  work.\n\n\n[vim-plug]: https://github.com/junegunn/vim-plug \n[tmux]: https://github.com/tmux/tmux\n[neovim-remote]: https://github.com/mhinz/neovim-remote\n[vim-registers-docs]: http://vimdoc.sourceforge.net/htmldoc/change.html#registers\n[vim-registers-tut]: https://www.brianstorti.com/vim-registers/\n[neovim]: https://neovim.io\n[process-substition]: https://en.wikipedia.org/wiki/Process_substitution\n[neomux-blog-post]: https://nikvdp.com/post/neomux\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikvdp%2Fneomux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikvdp%2Fneomux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikvdp%2Fneomux/lists"}