AwesomeWM - Vim - Tmux Navigator

Usually vim and tmux have their own dedicated keybinds for navigation. Christoomey's plugin vim-tmux-navigator allows you to the use the same keybinds for vim and tmux. This might be sufficient for floating wm users, but when using a tiling wm like awesomewm we can do better and add another layer.

awesomewm-vim-tmux-navigator lets you navigate seamlessly between system windows, vim splits and tmux panes by only using your awesomewm navigation keybinds (e.g. Mod4+hjkl). Every vim split and tmux pane is treated like a standalone system window, allowing you to forget your vim/tmux specific navigation hotkeys.

How does it work

It essentially works by sending the correct keypresses based on the context. Therefore the plugin has to detect whether the current focused application is vim, tmux or any other system window.

The plugin offers two methods of determining the focused application:

1. By using dynamic titles. The plugin tries to change the title (WM_NAME) of your terminal in order to differentitate between applications. However, not every shell-terminal-stack supports dynamic titles or is configured correctly out of the box. Minimal configurations are provided for zsh and bash.

2. By using pstree. This should theoretically work on every setup, but it might perform slower due to having an extra process to spawn. This method can be enabled by setting the experimental flag.

Installation

AwesomeWM

Clone the repo.

git clone https://github.com/intrntbrn/awesomewm-vim-tmux-navigator ~/.config/awesome/awesomewm-vim-tmux-navigator

It's not recommended to change the path since it's hardcoded in other configuration files.

Add your preferred navigation (focus) keybinds to rc.lua (e.g. Mod4+arrows or Mod4+hjkl):

require("awesomewm-vim-tmux-navigator") {
    up = {"Up", "k"},
    down = {"Down", "j"},
    left = {"Left", "h"},
    right = {"Right", "l"},
    mod = "Mod4",
    mod_keysym = "Super_L",
    --experimental = true
}

Please verify that mod and mod_keysym matches your actual awesomewm modifier key by using the terminal applications xev and xmodmap. For instance you might press the right super key and have to specify "Super_R" as your mod_keysym, or "Mod1" and "Alt_L" if you prefer to use the alt key.

Don't forget to remove your previously used navigation keybinds (or other conflicting keybinds) in rc.lua.

If you like to use your own custom directional focus function, you can do this by defining focus. Default is awful.client.focus.global_bydirection.

Vim

Install using your favorite package manager, e.g. vim-plug:

Plug 'intrntbrn/awesomewm-vim-tmux-navigator'

Remove christoomey/vim-tmux-navigator if you are using it.

Options:

let g:tmux_navigator_insert_mode = 1 to enable navigator keybinds in insert mode

Tmux

Add the following to your tmux.conf at the very bottom.

# Set title suffix to "- TMUX"
set-option -g set-titles on
set-option -g set-titles-string '#S: #W - TMUX'
# Smart pane switching with awareness of vim splits and system windows
is_vim="ps -o state= -o comm= -t '#{pane_tty}' \
	| grep -iqE '^[^TXZ ]+ +(\\S+\\/)?g?(view|n?vim?x?)(diff)?$'"
bind -n C-Left if-shell "$is_vim" "send-keys C-h" "run-shell 'sh ~/.config/awesome/awesomewm-vim-tmux-navigator/tmux_focus.sh left'"
bind -n C-Down if-shell "$is_vim" "send-keys C-j" "run-shell 'sh ~/.config/awesome/awesomewm-vim-tmux-navigator/tmux_focus.sh down'"
bind -n C-Up if-shell "$is_vim" "send-keys C-k" "run-shell 'sh ~/.config/awesome/awesomewm-vim-tmux-navigator/tmux_focus.sh up'"
bind -n C-Right if-shell "$is_vim" "send-keys C-l" "run-shell 'sh ~/.config/awesome/awesomewm-vim-tmux-navigator/tmux_focus.sh right'"
bind-key -T copy-mode-vi 'C-Left' "run-shell 'sh ~/.config/awesome/awesomewm-vim-tmux-navigator/tmux_focus.sh left'"
bind-key -T copy-mode-vi 'C-Down' "run-shell 'sh ~/.config/awesome/awesomewm-vim-tmux-navigator/tmux_focus.sh down'"
bind-key -T copy-mode-vi 'C-Up' "run-shell 'sh ~/.config/awesome/awesomewm-vim-tmux-navigator/tmux_focus.sh up'"
bind-key -T copy-mode-vi 'C-Right' "run-shell 'sh ~/.config/awesome/awesomewm-vim-tmux-navigator/tmux_focus.sh right'"

Troubleshooting

1. Make sure there are no conflicting keybindings.

2. Check https://github.com/christoomey/vim-tmux-navigator#troubleshooting.

3. Try to enable dynamic titles in your shell. Minimal configurations are provided for zsh and bash:

echo "source ~/.config/awesome/awesomewm-vim-tmux-navigator/dynamictitles.zsh" >> ~/.zshrc

or

echo "source ~/.config/awesome/awesomewm-vim-tmux-navigator/dynamictitles.bash" >> ~/.bashrc

After a correct installation the title of a tmux session should end with "- TMUX" and "- VIM" or "- NVIM" for vim or nvim sessions respectively. Check the title of the terminal client in your wm tasklist or by using the terminal application xprop (title is property WM_NAME).

In case your title does not change, your terminal and/or shell may not support dynamic titles. Try other.

4. Set experimental = true. The experimental mode does not require dynamic titles, but might be a bit slower.

Integration

This plugin can be used from everywhere and does not require any kind of import or reference.

Awesomewm: awesome.emit_signal("navigator::navigate", "left")

Shell: echo 'awesome.emit_signal("navigator::navigate", "up")' | awesome-client