Y.A.C.H.T - Yet Another Configuration Handler (for) Tmux

Supercharged and customizable tmux configuration that aims to appeal to power users while still being beginner friendly.

It is vastly based on these projects:

• Tmux Configuration
• Tmux Configuration by @arminveres (initial fork)
• .tmux
• tmux-plugins
• Tmux sysstat plugin
• t - the smart tmux session manager

Original Tmux Configuration animation for reference:

Table of contents

1. Features
2. Installation
3. Suggested shell configuration
4. General settings
5. Key bindings
6. Status line
7. Status menu
8. Nested tmux sessions
9. Copy mode
10. Clipboard integration
11. Themes and customization
12. GUI terminal integration

Features

• "C-a" <prefix> instead of "C-b" (screen like, easier to use with one hand)
• follow tmux-sensible (with a few minor changes)
• support for nested tmux sessions (local -> top bar / nested -> bottom bar)
• local vs remote specific session configuration (custom configuration applied to ssh sessions)
• scroll and copy mode improvements
• integration with OSX or Linux clipboard (works for local, remote, and local+remote nested session scenario)
• supercharged status line
• renew tmux and shell environment (SSH_AUTH_SOCK, DISPLAY, SSH_TTY) when reattaching back to old session
• newly created windows and panes retain current working directory
• monitor windows for activity/silence
• highlight focused pane, with toggle for pane status
• merge current session with existing one (move all windows)
• configurable visual theme/colors, with some elements borrowed from Powerline
• integration with 3rd party plugins: tmux-battery,tmux-prefix-highlight, tmux-online-status, tmux-resurrect, tmux-continuum, tmux-copycat, tmux-open, tmux-plugin-sysstat, t-smart-tmux-session-manager, tmux-plugin-sysstat
• all key bindings are listed in the "List key bindings" screen (do not include plugins, please refer to their documentation if needed)
• Status Menu with system info and some commonly used commands and toggles
• most stock key bindings still work as default, the most common ones can be used without <prefix>
• double-clicking empty area of the status bar creates a new window
• all key bindings can be disabled (OFF mode) when using a nested sessions (ssh, ect) or if a key binding conflicts
• Initial window is configured to use main-vertial layout with 60% width (main-horizontal also set o 60% height), which can be applied to new windows with a key-binding, as well as new panes follow the current layout (this can be overriden with custom key bindings, and the default layout and width/height easily changed in tmux.conf as well)
• resurrect and continuum plugins configured properly, save/restore pane buffer enabled, visible status via Stautus Menu, <prefix> C-s saves the session and <prefix> C-r restores it, auto-restore and auto-save can be configured in the main tmux.conf
• tmux.conf is completely documented, so it should be easy to change the default settings or customize it even further

Status line widgets:

• CPU, memory and swap usage (sysstat widgets)
• battery information
• username (root aware, thanks to this) and hostname, current date and time
• visual indicator when <prefix> is pressed
• visual indicator when Copy mode is active
• visual indicator when Synchronization mode is active
• visual indicator when pane is zoomed
• visual indicator when main sessions is locked (OFF mode)
• online/offline visual indicator
• toggle visibility of sysstat and battery widgets via Status Menu
• toggle visibility of status line via Status Menu or key binding

TODO

• create a menu/popup with some help information

Installation

Prerequisites:

• tmux -V >= 3.2
• Linux, tested on Arch Linux (tmux 3.3a) and Ubuntu 22.04 (tmux 3.2a)
• macOS (not tested, but it should work)

To install YACHT:

$ git clone <repo address> # or download and extract the code
$ ./yacht/install.sh

install.sh script does the following:

• copy files to ~/.config/tmux directory
• existing ~/.tmux.conf is moved to '~/.config/tmux/tmux.conf.home`
• existing ~/.config/tmux/tmux.conf is renamed to 'tmux.conf.config`
• Tmux Plugin Manager is installed at default location ~/.config/tmux/plugins/tpm, unless already present
• required tpm plugins are installed
• fix the padding of sysstat widgets

Finally, you can jump into a new tmux session:

$ tmux new

PS: if the status line or your shell prompt looks broken, and you are sure that a font with Powerline support is being used (like a Nerd font, for instance), make sure your locale supports UTF8 and/or start tmux with the -u flag to force UTF8 support.

Suggested shell configuration

Recent versions of fzf can use tmux menus to show its search results, add something like this to the environment variables (more info here):

export FZF_TMUX_OPTS="-p 60%,70%"

And in order to display useful info in the pane status when it is enabled, make sure prompt precmd has something like this:

printf "\033]0;%s@%s:%s\007" "${USER}" "${${HOSTNAME:-$HOST}%%.*}" "${PWD/#$HOME/~}"

General settings

Most tmux-sensible suggestions are followed, with these changes:

• display-time 2000 # ststus messages display time duration = 2s
• status-interval 3 # status bar update interval = 3s
• default-terminal tmux-256color # instead of screen-256color
• status-keys will follow your $EDITOR / $VISUAL environment variable, like stock tmux
• reload tmux configuration file is mapped to <prefix> C-r

Other default configuration, as suggested by tmux-sensible or not:

• Windows and pane indexing starts from 1 rather than 0
• Scrollback history limit is set to 50000
• Aggresive resizing is on
• Mouse support in on.
• escape-time is 0 to avoid problems with programs like vim/neovim that use ESC key
• Focus application events is enabled
• Detach on destroy is disabled (instead of exiting, attach to next session, if available)

256 color palette support is turned on, make sure that your parent terminal is configured propertly. See here and there

Key bindings

All new and custom key bindings are listed in the List key bindings screen (<prefix> + ?).

Tip: you can search this screen using common vim/less commands.

The key bindings were chosen to make it easier to remember them for new users, while still keeping the basic ones for long time tmux users. Of course, they can be changed in the tmux.conf file if needed.

The most used ones were added as default so the basic funcionality is available without the need to press <prefix> first:

Key binding	Description
M-t	Create new window
M-n	Split window, and apply layout
M-x	Kill pane, with confirmation
M-arrows	Naviagte panes and windows
C-Tab	Go to most recent used window
C-S-Up	Enter Copy mode, PageDown to the very bottom cancels it

These key bindings can be mapped to your GUI terminal keys of choice, but this needs to be done manually. See GUI terminal integration section below.

Status line

Window tabs use Powerline arrows glyphs, so you need to install Powerline enabled font to make this work. See Powerline docs for instructions and here is the collection of patched fonts for powerline users. Your preferred Nerd font should work as well.

Most modes, like Copy, Synchronization and Zoom have visual indicators. Status bar can be hidden using <prefix> C-t key binding, or use the Status Menu to toggle some (somewhat CPU intensive widgets) on/off.

Status menu

Using <prefix> Home will display handy menu with some configurartion options and toggles. This is also available via a click with the secondary mouse button on the right area of the status bar. Some options affect only the [P]ane, [W]indow or the whole [S]ession, and the associated key binding is also visible.

Nested tmux sessions

When in outer session, simply press F12 to toggle off all keybindings handling in the outer session. Now work with inner session using the same keybinding scheme and same keyprefix. Press F12 to turn on outer session back.

You might notice that when key bindings are "OFF", special [OFF] visual indicator is shown in the status line, and status line changes its style (colored to gray).

Local and remote sessions

Remote session is detected by existence of $SSH_CLIENT variable. When session is remote, following changes are applied:

• status line is docked to bottom; so it does not stack with status line of local session;
• some widgets are removed from status line.n.

You can apply remote-specific settings by extending ~/.config/tmux/.tmux.remote.conf file.

Copy mode

There are some tweaks to copy mode and scrolling behavior, you should be aware of.

There is a root keybinding to enter Copy mode: C-S-Up. Once in copy mode, you have several scroll controls:

• scroll by line: M-Up, M-down
• scroll by half screen: M-PageUp, M-PageDown
• scroll by whole screen: PageUp, PageDown
• scroll by mouse wheel, scroll step is changed from 5 lines to 2

Space starts selection, Enter copies selection and exits copy mode. List all items in copy buffer using <prefix> C-b, and paste most recent item from buffer using <prefix> p.

y just copies selected text and is equivalent to Enter, Y copies whole line, and D copies by the end of line. Like most modes, pressing Q will cancel and exit the mode.

Other features are available via tmux-copycat and tmux-open plugins, please refer to their documentation.

Also, note that when text is copied any trailing new lines are stripped. So, when you paste buffer in a command prompt, it will not be immediately executed.

You can also select text using mouse. Default behavior is to copy text and immediately cancel copy mode on MouseDragEnd event. This is annoying, because sometimes I select text just to highlight it, but tmux drops me out of copy mode and reset scroll by the end. So this behavior was changed: MouseDragEnd does not execute copy-selection-and-cancel action. Text is copied, but copy mode is not cancelled and selection is not cleared. You can then reset selection by a single mouse click.

Clipboard integration

Sharing with the system clipboard was tested on Linux, at least for the local connection. There are some changes applied for macOS users, as explained here, but this was not tested.

Themes and customization

All colors related to theme are declared as variables. You can change them in ~/.config/tmux/tmux.conf.

GUI terminal integration

These guides will help in order to make your preferred GUI terminal keybings work with tmux:

• iTerm2
• Alacritty, Kitty, WezTerm
• foot (text-bindings in foot.ini(5))

Original Tmux Configuration screenshot for reference: