Tmux Configuration - Gentleman.Dots

Overview

Tmux is a terminal multiplexer that lets you switch between several programs in one terminal, detach them and reattach them to a different terminal. The Gentleman.Dots Tmux configuration includes carefully selected plugins, Vim-style navigation, and a beautiful Kanagawa theme.

The prefix key has been changed from Ctrl+b to Ctrl+a for better ergonomics.

Key Features

Vim Navigation

hjkl keybindings for intuitive pane movement

Kanagawa Theme

Beautiful color scheme with git, CPU, and RAM indicators

Session Persistence

Save and restore sessions with tmux-resurrect

Floating Windows

Quick scratch terminal with Alt+g

Installation

Install Tmux and TPM

brew install tmux
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

Copy Configuration

mkdir -p ~/.tmux
cp -r GentlemanTmux/.tmux/* ~/.tmux/
cp GentlemanTmux/.tmux.conf ~/

Install Plugins

tmux new-session -d -s plugin-installation 'source ~/.tmux.conf; tmux run-shell ~/.tmux/plugins/tpm/bin/install_plugins'
tmux kill-session -t plugin-installation

Start Tmux

tmux

Configuration Breakdown

Plugins

The configuration includes these essential plugins:

tmux.conf

# Plugin Manager
set -g @plugin 'tmux-plugins/tpm'

# Sensible defaults
set -g @plugin 'tmux-plugins/tmux-sensible'

# Clipboard management
set -g @plugin 'tmux-plugins/tmux-yank'

# Vim-Tmux navigation
set -g @plugin 'christoomey/vim-tmux-navigator'

# Session persistence
set -g @plugin 'tmux-plugins/tmux-resurrect'

# Keybinding helper
set -g @plugin 'alexwforsythe/tmux-which-key'

# Kanagawa theme
set -g @plugin 'Nybkox/tmux-kanagawa'

Press Ctrl+a + I (capital i) inside Tmux to install new plugins after adding them to the config.

Theme Configuration

The Kanagawa theme is customized with status indicators:

tmux.conf

set -g @kanagawa-theme 'Kanagawa'
set -g @kanagawa-plugins "git cpu-usage ram-usage"
set -g @kanagawa-ignore-window-colors true

Available plugins for the status bar:

git - Current git branch
cpu-usage - CPU utilization percentage
ram-usage - Memory usage
battery - Battery status (useful for laptops)
time - Current time

Prefix Key

The prefix has been changed to Ctrl+a for better ergonomics:

tmux.conf

unbind C-b
set -g prefix C-a
bind C-a send-prefix

If you use Ctrl+a to jump to the beginning of the line in bash/zsh, press it twice: Ctrl+a Ctrl+a

Pane Splitting

Intuitive split commands:

tmux.conf

unbind %
unbind '"'
bind v split-window -h -c "#{pane_current_path}"
bind d split-window -v -c "#{pane_current_path}"

Usage:

Ctrl+a then v - Vertical split (left/right)
Ctrl+a then d - Horizontal split (down)

Both commands open the new pane in the current working directory.

Vim Mode

Vim-style keybindings in copy mode:

tmux.conf

set -g mode-keys vi

Clipboard integration (platform-aware):

tmux.conf

if-shell 'uname | grep -q Darwin' \
  'bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"' \
  'bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "clip"'

Floating Scratch Window

Quick access to a floating terminal:

tmux.conf

bind-key -n M-g if-shell -F '#{==:#{session_name},scratch}' {
  detach-client
} {
  display-popup -d "#{pane_current_path}" -E "tmux new-session -A -s scratch"
}

Usage: Press Alt+g to toggle a floating scratch terminal

Essential Keybindings

Session Management

Keybinding	Action
`Ctrl+a` `d`	Detach from session
`Ctrl+a` `K`	Kill all other sessions (prompts for confirmation)
`tmux attach -t <name>`	Reattach to session
`tmux ls`	List all sessions

Window (Tab) Management

Keybinding	Action
`Ctrl+a` `c`	Create new window
`Ctrl+a` `n`	Next window
`Ctrl+a` `p`	Previous window
`Ctrl+a` `0-9`	Switch to window number
`Ctrl+a` `,`	Rename current window
`Ctrl+a` `&`	Kill current window

Pane Management

Keybinding	Action
`Ctrl+a` `v`	Split pane vertically (left/right)
`Ctrl+a` `d`	Split pane horizontally (up/down)
`Ctrl+a` `h/j/k/l`	Navigate panes (Vim style)
`Ctrl+a` `x`	Kill current pane
`Ctrl+a` `z`	Toggle pane zoom (fullscreen)
`Ctrl+a` `{`	Move pane left
`Ctrl+a` `}`	Move pane right

Copy Mode

Keybinding	Action
`Ctrl+a` `[`	Enter copy mode
`Space`	Start selection (in copy mode)
`y`	Copy selection (in copy mode)
`Enter`	Copy selection and exit (in copy mode)
`q`	Exit copy mode
`Ctrl+a` `]`	Paste buffer

Plugin-Specific

Keybinding	Action
`Alt+g`	Toggle floating scratch window
`Ctrl+a` `?`	Show which-key helper
`Ctrl+a` `I`	Install new plugins
`Ctrl+a` `U`	Update plugins
`Ctrl+a` `Ctrl+s`	Save session (resurrect)
`Ctrl+a` `Ctrl+r`	Restore session (resurrect)

Advanced Usage

Session Management

Create a new named session:

tmux new -s project-name

Attach to existing session:

tmux attach -t project-name
# or shorthand
tmux a -t project-name

List all sessions:

tmux ls

Kill specific session:

tmux kill-session -t project-name

Custom Layouts

Gentleman.Dots includes Vim-Tmux integration. When you navigate between Vim splits and Tmux panes using Ctrl+h/j/k/l, the navigation is seamless.

Status Bar Position

The status bar is positioned at the top:

tmux.conf

set -g status-position top

To move it to the bottom, change this to:

tmux.conf

set -g status-position bottom

Mouse Support

Mouse support is enabled by default:

tmux.conf

set -g mouse on

This allows you to:

Click to select panes
Drag pane borders to resize
Click status bar to switch windows
Scroll with mouse wheel in copy mode

Troubleshooting

Colors look wrong in Tmux

Ensure your terminal supports true color and the following is in your config:

tmux.conf

set -g default-terminal "tmux-256color"
set -ga terminal-overrides ",*:Tc"

For Alacritty users, make sure TERM is set to alacritty in your terminal config.

Vim navigation not working between Tmux and Neovim

Ensure the vim-tmux-navigator plugin is installed in both Tmux and Neovim. The Gentleman.Dots Neovim config already includes this.In Tmux, verify the plugin is loaded:

tmux show-environment -g | grep vim-tmux-navigator

Clipboard not working

On macOS: Ensure pbcopy is availableOn Linux/WSL: Install xclip or use the custom clip script:

# For X11
sudo apt-get install xclip

# For Wayland
sudo apt-get install wl-clipboard

Plugins not loading

Make sure TPM is installed and initialized:

# Check if TPM exists
ls ~/.tmux/plugins/tpm

# Reload Tmux config
tmux source ~/.tmux.conf

# Install plugins (inside Tmux)
# Press: Ctrl+a then I (capital i)

Customization Tips

Change Theme Colors

The Kanagawa theme can be customized. Edit the plugin settings:

tmux.conf

set -g @kanagawa-theme 'Kanagawa'  # Options: Kanagawa, Dragon, Wave

Add More Status Bar Plugins

tmux.conf

set -g @kanagawa-plugins "git cpu-usage ram-usage battery time"

Change Window Indexing

By default, windows start at 1:

tmux.conf

set -g base-index 1
setw -g pane-base-index 1

Increase Scrollback Buffer

Add to your config:

tmux.conf

set -g history-limit 50000

Resources

Tmux GitHub

Official Tmux repository

TPM

Tmux Plugin Manager

Tmux Cheatsheet

Comprehensive keybinding reference

vim-tmux-navigator

Seamless Vim-Tmux navigation

Get Started

Terminal Emulators

Shells

Window Managers

Neovim Configuration

AI Integration

Platform-Specific Guides

Advanced

​Overview

​Key Features

Vim Navigation

Kanagawa Theme

Session Persistence

Floating Windows

​Installation

​Configuration Breakdown

​Plugins

​Theme Configuration

​Prefix Key

​Pane Splitting

​Vim Mode

​Floating Scratch Window

​Essential Keybindings

​Session Management

​Window (Tab) Management

​Pane Management

​Copy Mode

​Plugin-Specific

​Advanced Usage

​Session Management

​Custom Layouts

​Status Bar Position

​Mouse Support

​Troubleshooting

​Customization Tips

​Change Theme Colors

​Add More Status Bar Plugins

​Change Window Indexing

​Increase Scrollback Buffer

​Resources

Tmux GitHub

TPM

Tmux Cheatsheet

vim-tmux-navigator

Build docs developers (and LLMs) love

Overview

Key Features

Installation

Configuration Breakdown

Plugins

Theme Configuration

Prefix Key

Pane Splitting

Vim Mode

Floating Scratch Window

Essential Keybindings

Session Management

Window (Tab) Management

Pane Management

Copy Mode

Plugin-Specific

Advanced Usage

Session Management

Custom Layouts

Status Bar Position

Mouse Support

Troubleshooting

Customization Tips

Change Theme Colors

Add More Status Bar Plugins

Change Window Indexing

Increase Scrollback Buffer

Resources