tmux-nvr

A tmux plugin for using session-specific Neovim instances with neovim-remote

---

neovim-remote allows you to control nvim processes from the shell using nvr. You might then want nvr to control nvim processes in your current tmux session, rather than another one. This requires setting a unique NVIM_LISTEN_ADDRESS for each of your sessions.

tmux-nvr automates the creation of session-specific values for NVIM_LISTEN_ADDRESS so that nvr will always refer to an nvim process in your current session.

tmux-nvr also provides nvr-tmux, an executable which automates switching to the nvim process controlled by nvr.

Requirements

• tmux 3.0+
  • nvr-tmux requires tmux 3.2+
• Neovim
• neovim-remote

Installation Using TPM

Install tmux-nvr using the tmux plugin manager. Add the following line to your tmux.conf.

set -g @plugin 'carlocab/tmux-nvr'

Press prefix + I (capital i, as in Install) to fetch the plugin.

Next, add this snippet to your zshrc or bashrc.

if [ -n "$TMUX" ]; then
    eval "$(tmux show-environment -s NVIM_LISTEN_ADDRESS 2> /dev/null)"
else
    export NVIM_LISTEN_ADDRESS=/tmp/nvimsocket
fi

The else statement is optional. Nevertheless, it is a good idea to include it. nvr is known to produce errors when it is used without this being set. You may wish to check the permissions of /tmp if you are on a multi-user system.

Optional: Zsh Plugin Installation with OhMyZsh

If you use OhMyZsh, instead of using the snippet above, you can use the packaged zsh plugin. First, symlink the tmux-nvr directory into $ZSH_CUSTOM using

ln -s ~/.tmux/plugins/tmux-nvr ~ZSH_CUSTOM/plugins

Your tmux plugins may be installed in a different location. One can typically verify this location using echo $TMUX_PLUGIN_MANAGER_PATH.

Finally, add tmux-nvr to the plugins array in your zshrc.

plugins=($plugins tmux-nvr)

The plugin will also add nvr-tmux to your PATH, if your version of tmux is new enough.

Manual Installation

Clone this repository using

git clone https://github.com/carlocab/tmux-nvr ~/path/to/tmux-nvr

Add the following line to your tmux.conf.

run-shell ~/path/to/tmux-nvr/nvr.tmux

Then, follow the instructions for your *rc files in the previous section.

Usage

It should just work.

An earlier version of tmux-nvr required setting a @tmux-nvr-hook-index option to avoid overriding pre-defined session-created hooks. This is no longer necessary.

nvr-tmux

nvr-tmux is an executable found in the bin directory. It automates switching to nvim whenever there is an existing instance of nvim connected to NVIM_LISTEN_ADDRESS.

It passes all its arguments to nvr, so it can be used in exactly the same way. For example, to edit a file in an existing instance of nvim using nvr, you would run

nvr file.txt

This opens file.txt in nvim, but leaves you in the shell you called nvr from. To immediately switch the current pane to nvim as it opens the file, run

nvr-tmux file.txt

nvr-tmux can serve as a drop-in replacement for nvr, even if you are not running tmux.

To use nvr-tmux, either add the bin directory to your PATH, or symlink bin/nvr-tmux to a directory in your PATH. This is done automatically by the packaged zsh plugin.

nvr-tmux requires tmux 3.2 or above.

Why not use a shell function?

nvr-tmux has been most useful for me as a git editor, as described in the neovim-remote README. git does not recognise shell functions as editors, so any shell function you use for this purpose will need to be turned into an executable script.

I've saved you the trouble of doing that with nvr-tmux.

Miscellaneous

For bug reports or questions, please file an issue here.

tmux-nvr may behave unpredictably if you script the creation of several tmux sessions at a time. If this causes problems, please file an issue using the link above.

Wishlist

Here are improvements I hope to be able to work on (in no particular order):

1. Window-specific nvim instances
2. nvr-tmux backwards-compatibility
3. Simpler installation procedure
4. Vim-compatibility
5. tmux-nvr usage demo

Pull requests are welcome.

Related Projects

https://github.com/daplay/tmux_nvr