Sailor.vim is a (n)vim and tmux plugin which allows a seamless navigation between kitty windows, tmux panes and (n)vim buffers.
Locally all the craziest things should work. This means you should be able to sailor between any sort of kitty/tmux/nvim split nomatter its nature. Let's try to illustrate it:
+ ---------------------------- + ------------------------ +
| kitty window | kitty window |
| | |
| + ------- tmux ------- + | |
| | | | |
| | + --- nvim --- + | | |
| | | | | | |
| | | buffer | | | |
| | | | | | |
| | + ------------ + | | |
| | | | |
| + -------------------- + + ------------------------ +
| | | | |
| | tmux pane | | + ----- nvim ----- + |
| | | | | | |
| | | | | buffer | |
| | | | | | |
| + -------------------- + | + ---------------- + |
| | |
+ ---------------------------- + ------------------------ +
This plugin provides the following mappings which allow you to move between vim splits, tmux panes, and kitty windows seamlessly.
<ctrl-h>
=> Left<ctrl-j>
=> Down<ctrl-k>
=> Up<ctrl-l>
=> Right
The install.sh
script will create some symbolic links for kitty so it is
straightforward to get it running. You will need to restart kitty so all
the configuration works fine. This file runs after the vim/nvim plugin is
installed.
- This requires kitty version higher than 0.13.1 and lower than 0.24.x.
- Requires newer version of tmux version higher than 2.7.
Use your favorite plugin manager (packer.nvim
in the example) and add this
repository to your plugin list
packer.use {
"marromlam/sailor.vim",
run = "./install.sh"
}
When installing the vim/nvim plugin, the installer is going to create
pass_keys.py
and neighboring_window.py
kittens into
~/.config/kitty/kittens
. We still need to configure two more things:
- Add the following to your
~/.config/kitty/kitty.conf
file:
map ctrl+j kitten kittens/pass_keys.py kittens/neighboring_window bottom ctrl+j
map ctrl+k kitten kittens/pass_keys.py kittens/neighboring_window top ctrl+k
map ctrl+h kitten kittens/pass_keys.py kittens/neighboring_window left ctrl+h
map ctrl+l kitten kittens/pass_keys.py kittens/neighboring_window right ctrl+l
By default vim-kitty-navigator
uses the name of the current foreground
process to detect when it is in a (neo)vim session or not. If that doesn't
work, (or if you want to support applications other than vim) you can supply a
fourth optional argument to the pass_keys.py
call in your kitty.conf
file
to match the process name.
map ctrl+j kitten kittens/pass_keys.py kittens/neighboring_window bottom ctrl+j "^.* - nvim$"
map ctrl+k kitten kittens/pass_keys.py kittens/neighboring_window top ctrl+k "^.* - nvim$"
map ctrl+h kitten kittens/pass_keys.py kittens/neighboring_window left ctrl+h "^.* - nvim$"
map ctrl+l kitten kittens/pass_keys.py kittens/neighboring_window right ctrl+l "^.* - nvim$"
- Enable kitty
allow_remote_control
andlisten_on
option:
Set it on the ~/.config/kitty/kitty.conf
file:
allow_remote_control yes
listen_on unix:/tmp/mykitty
OR
Start kitty with the listen_on
option so that vim can send commands to it.
kitty -o allow_remote_control=yes --listen-on unix:/tmp/mykitty
The listening address can be customized in your .vimrc
or init.lua
by setting
vim.g.kitty_navigator_listening_on_address = 'unix:/tmp/mykitty'
```.
### tmux.
If you're using [TPM](https://github.com/tmux-plugins/tpm),
just add this snippet to your tmux.conf:
```conf
set -g @plugin 'marromlam/sailor.vim'
And update your tmux session, tipically prefix
+I
.
If you do not want to ue TPM, then you should just copy-paste
the .tmux
file to your tmux.conf
file.
With the settings above, navigation should work well locally. But if you need kitty-tmux navigation also work through ssh, follow steps below:
- Install kitty on your remote machine, here I show how to do it in linux using linuxbrew: How To.
wget https://github.com/kovidgoyal/kitty/releases/download/v0.20.3/kitty-0.20.3-x86_64.txz -O kitty.txz
mkdir $HOMEBREW_PREFIX/Cellar/kitty
tar xf kitty.txz -C $HOMEBREW_PREFIX/Cellar/kitty
ln -sf $HOMEBREW_PREFIX/Cellar/kitty/bin/kitty $HOMEBREW_PREFIX/bin
rm kitty.txz
With kitty installed on your remote system and remote control enabled, your should be able to use remote control from ssh. But because of reasons explained here, it won't work from inside tmux. So we're going to need some workarounds.
- Set remote port forwarding when using SSH.
ssh -R 50000:${KITTY_LISTEN_ON#*:} user@host
The remote TCP port 50000 can be changed to anything depending on your needs.
You can put it as an alias on your shell rc file so you don't type it all the time.
alias ssh='ssh -R 50000:${KITTY_LISTEN_ON#*:}'
- Add the following snippet to your remote machine's
.zshrc
or something similar on other shell:
# Set KITTY_PORT env variable
if [[ $SSH_TTY ]] && ! [ -n "$TMUX" ]; then
export KITTY_PORT=`kitty @ ls 2>/dev/null | grep "[0-9]:/tmp/mykitty" | head -n 1 | cut -d : -f 1 | cut -d \" -f 2`
fi
Explanation:
- Source kitty path so the binary can be called from anywhere
- Set the KITTY_PORT environment variable automatically from the foreground process that call ssh.
- Set terminal key binding for changing kitty window when not using tmux
- Don't forget to install the tmux plugin on your remote system also. And copy
neighboring_window.py
to your remote machine ~/.config/kitty directory.
This plugin is a fork from vim-kitty-navigator extending it's capabilities to also work with tmux pane navigation. The aim is to make navigation between Kitty windows, tmux panes, and vim splits seamless. With some extra configuration, kitty-tmux navigation works even through SSH!