This plugin is a port of Chris Toomey's vim-tmux-navigator plugin. Credit is also due to vim-kitty-navigator.

When combined with a set of iTerm2 key bindings and scripts, as well as vim's title option, the plugin will allow you to navigate seamlessly between vim and iTerm2 window splits using a consistent set of hotkeys.

NOTE 1: This requires iTerm2 v3.3 or higher, in order to support the python API.

NOTE 2: This requires python3 feature, which, on neovim, involves only installing python3 and pynvim. Developed and used on neovim. Untested on vanilla vim (I'd actually be a bit surprised if it worked).

NOTE 3: This plugin is quite hacky, and as such assumes you know basic unix shell skills, like how to make symbolic links and so on. If you are not at that level, this plugin will prove frustrating.

This plugin provides the following mappings which allow you to move between Vim panes and iTerm2 splits seamlessly.

• <cmd-h> → Left
• <cmd-j> → Down
• <cmd-k> → Up
• <cmd-l> → Right

As this software is an integration between iTerm2, vim, and python, it will require some configuration in all three software packages.

If you don't have a preferred installation method, I recommend using vim-plug. Asuming you have vim-plug installed and configured, the following steps will install the plugin:

Add the following line to your ~/.vimrc or ~/.config/nvim/init.vim file.

Plug 'jdelkins/vim-iterm2-navigator', {'branch': 'main', 'do': {-> iterm2_navigator#install()}}
set title

Then run

:PlugInstall

This is the trickiest part, requiring a number of steps to set up.

1. Symlink the scripts for iTerm2

The iterm2_navigator#install() function should handle this part for you (on macOS, the only platform where iTerm2 is available), but in case you want to manually install, follow this general procedure.

$ mkdir -p "~/Library/Application Support/iTerm2/Scripts/AutoLaunch"
$ ln -s «vimdir»/bundle/vim-iterm2-navigator/iterm2-scripts/AutoLaunch/jump_pane.py "~/Library/Application Support/iTerm2/Scripts/AutoLaunch/"

2. Enable iTerm2 python API (this will involve downloading the python runtime).

• Enable the following setting:
  
  Preferences→General→Magic→Enable Python API

• Restart iTerm2 or else ensure that the jump_pane.py script is running

3. Create Key Bindings

• Under Preferences→Keys→Key Bindings, Click + to create a new key binding
• For shortcut key, enter ⌘h
• For Action, choose Invoke Script Function...
• In the function call box, enter: do_jump(session_id: id, direction: "h")

Repeat the above (#3) procedure, replacing h with j, k, and l. The end result should be four key bindings, each calling the do_jump RPC coroutine respectively with parameters of h, j, k, and l.

Note: You can use any key combination instead of ⌘h etc. Vim will never see these keystrokes, as they will be captured by iTerm2, and the python script will translate them to intermediate keystrokes to trigger the Vim maps defined in the plugin. These intermediate maps are designed to be (hopefully) distinct.

Advanced info: These intermediate keystrokes are <C-_>{h,j,k,l}. If you want to change them (presumably due to a conflict with another map you are using), then you'll have to edit the python and vim scripts.

This tool requires the iterm2 python module as well as the python interpreter in vim. For neovim, this requires the pynvim python module and a system installation of python3 itself. Use with vanilla vim should work in theory (as long the binary was built with python3 support) but it's completely untested by me.

pip install pynvim
pip install iterm2

If these supporting modules are not available, this package will silently not function. If you think it should be working but isn't, double check the requrements in this section.

vim-iterm2-navigator uses the window title to detect when it is in a (neo)vim session or not. You must therefore enable the title setting, which is not on by default:

set title

The default titlestring ends with either - VIM or - NVIM for vim or neovim, respectively. The python scripts rely on this pattern to determine whether vim is running in the window. If you have a non-standard titlestring set for vim, for this plugin to work, it must also end with one of these strings. For example:

let &titlestring='%t - NVIM'

This project is licensed under the same terms as Vim itself.

Copyright (c) Joel D. Elkins [email protected]. All rights reserved.