Tmux Configuration Guide

This repository contains a professional and highly optimized tmux setup.

---

Installation

1. Download the configuration

Clone this repository or download the tmux.conf file directly:

# Clone the repository
git clone https://github.com/luizeof/tmux.conf.git ~/.tmux-conf

# Create a symlink to your home directory
ln -s ~/.tmux-conf/tmux.conf ~/.tmux.conf

2. Install Tmux Plugin Manager (TPM)

If you don't have TPM installed yet, run:

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

3. Load the configuration

Open tmux and press prefix + I (default prefix is Ctrl + b) to fetch and install all plugins.

---

What is tmux?

tmux is a terminal multiplexer — it lets you run multiple terminal sessions inside a single window, keep sessions alive after disconnecting, and split your screen into panes. Essential for remote servers and power users.

Core concepts:

Concept	Description
Session	A collection of windows. Survives disconnection.
Window	Like a browser tab — a full-screen view inside a session.
Pane	A split within a window. Multiple panes share one window.
Prefix	Ctrl + b — pressed before every tmux keybind.

---

Getting Started

# Start a new session
tmux

# Start a named session
tmux new -s myproject

# List sessions
tmux ls

# Attach to last session
tmux attach

# Attach to named session
tmux attach -t myproject

# Kill a session
tmux kill-session -t myproject

After opening tmux, press prefix + I (capital i) to install all plugins.

---

Default Keybindings

All keybinds require pressing Ctrl + b first, then the key.

Sessions

Keybind	Action
prefix + s	List and switch sessions (interactive)
prefix + $	Rename current session
prefix + d	Detach from session (session keeps running)
prefix + (	Switch to previous session
prefix + )	Switch to next session
prefix + L	Switch to last (previously used) session

Windows

Keybind	Action
prefix + c	Create new window
prefix + ,	Rename current window
prefix + &	Kill current window
prefix + n	Next window
prefix + p	Previous window
prefix + l	Last window (toggle)
prefix + w	List and switch windows (interactive)
prefix + 0–9	Switch to window by number
prefix + '	Prompt for window number to switch to
prefix + .	Move window to a different index
prefix + f	Find window by name

Panes

Keybind	Action
prefix + %	Split vertically (left/right)
prefix + "	Split horizontally (top/bottom)
prefix + o	Rotate to next pane
prefix + ;	Toggle to last active pane
prefix + x	Kill current pane
prefix + z	Zoom/unzoom pane (toggle fullscreen)
prefix + q	Show pane numbers (press number to jump)
prefix + {	Swap pane with previous
prefix + }	Swap pane with next
prefix + Alt+1–5	Switch to preset pane layouts (even-h, even-v, main-h, main-v, tiled)
prefix + !	Break pane into its own window
prefix + m	Mark pane
prefix + M	Clear marked pane
↑ ↓ ← →	Navigate panes by direction
prefix + Ctrl + ↑↓←→	Resize pane (1 cell)
prefix + Alt + ↑↓←→	Resize pane (5 cells)

Copy Mode

Keybind	Action
prefix + [	Enter copy mode
prefix + ]	Paste last copied buffer
prefix + #	List paste buffers
prefix + =	Choose buffer to paste from list
prefix + -	Delete most recent buffer
q (in copy mode)	Exit copy mode
Space (in copy mode)	Start selection
Enter (in copy mode)	Copy selection and exit
/ (in copy mode)	Search forward
? (in copy mode)	Search backward

Misc

Keybind	Action
prefix + :	Open tmux command prompt
prefix + ?	List all keybindings
prefix + r	Reload tmux config
prefix + t	Show clock
prefix + i	Show window info
prefix + ~	Show tmux messages
prefix + D	Choose a client to detach
prefix + E	Spread panes evenly
prefix + Ctrl+z	Suspend tmux client

---

Plugins

Core

Plugin	Description
tmux-plugins/tpm	Plugin manager
tmux-plugins/tmux-sensible	Sensible defaults

TPM keybinds:

Keybind	Action
prefix + I	Install plugins
prefix + U	Update plugins
prefix + Alt+u	Remove unused plugins

---

Navigation & Pane Control

tmux-pain-control

Consistent, intuitive pane splitting and resizing keybinds.

Keybind	Action	Replaces default
prefix + |	Split vertically (left/right)	prefix + % still works
prefix + -	Split horizontally (top/bottom)	Overrides delete-buffer (rarely used)
prefix + \	Split full-width vertically	—
prefix + _	Split full-height horizontally	—
prefix + h	Select pane left	—
prefix + j	Select pane down	—
prefix + k	Select pane up	—
prefix + l	Select pane right	last-window restored after plugin loads
prefix + H/J/K/L	Resize pane (5 cells)	—

christoomey/vim-tmux-navigator

Navigate between tmux panes and vim splits with the same keys.

Keybind	Action
Ctrl + h	Move left
Ctrl + j	Move down
Ctrl + k	Move up
Ctrl + l	Move right
Ctrl + \	Move to previous pane

No prefix needed. Works transparently inside vim/neovim.

---

Mouse

NHDaly/tmux-better-mouse-mode

Improves mouse behavior in tmux.

Feature	Behavior
Scroll down in copy mode	Exits copy mode automatically
Scroll over pane	Does not change active pane
Scroll in vim/less/man	Sends scroll events to the app (alternate buffer)

---

Copy & Clipboard

tmux-plugins/tmux-yank

Copy text to the system clipboard.

Keybind	Context	Action
prefix + y	Normal	Copy text on command line
prefix + Y	Normal	Copy current working directory
y	Copy mode	Copy selection to clipboard
Y	Copy mode	Copy selection and paste to command line

CrispyConductor/tmux-copy-toolkit

Enhanced copy mode utilities.

Keybind	Action
prefix + e	Activate copy toolkit

abhinav/tmux-fastcopy

Hint-based copying (vimium-style). Highlights text patterns on screen and lets you copy them by typing short hint letters.

Keybind	Action
prefix + F	Activate fastcopy hints

Recognizes: URLs, IPs, Git hashes, file paths, UUIDs, hex colors, numbers, and more.

Uses prefix + F (uppercase) — prefix + f is preserved for tmux's built-in find-window.

---

URL & File Opening

tmux-plugins/tmux-open

Open highlighted text from copy mode.

Keybind	Context	Action
o	Copy mode	Open with system default app
Ctrl + o	Copy mode	Open with $EDITOR
Shift + s	Copy mode	Search selection in browser

wfxr/tmux-fzf-url

Lists all visible URLs with fzf for quick opening.

Keybind	Action
prefix + u	Open URL picker

u is not a default tmux binding — no conflict.

---

Session Management

tmux-plugins/tmux-resurrect

Save and restore the entire tmux environment across reboots.

Keybind	Action
prefix + Ctrl+s	Save session
prefix + Ctrl+r	Restore session

Saves: windows, panes, working directories, pane contents, running programs.

tmux-plugins/tmux-continuum

Automatic session saving and restoration.

Feature	Value
Auto-save interval	Every 10 minutes
Auto-restore on start	Enabled

No keybinds — works automatically in the background.

omerxx/tmux-sessionx

Full-featured session manager with fzf preview.

Keybind	Action
prefix + S	Open session manager

Inside sessionx: Ctrl+d delete session, Ctrl+r rename, Tab switch preview.

Uses prefix + S (uppercase) — prefix + o is preserved for tmux's built-in rotate-pane.

---

Fuzzy Finder

sainnhe/tmux-fzf

Manage sessions, windows, panes, and run commands via fzf.

Keybind	Action
prefix + F (uppercase)	Open tmux-fzf menu

---

UI Helpers

Freed-Wu/tmux-digit

Visual number overlay for quick window switching.

Keybind	Action
prefix + 0–9	Jump directly to window by index

anghootys/tmux-ip-address

Displays the machine's current IP address in the status bar. No keybinds.

tmux-plugins/tmux-prefix-highlight

Highlights the status bar when the prefix key is active, in copy mode, or in sync mode. No keybinds.

alexwforsythe/tmux-which-key

Shows an interactive popup listing all available keybinds — no need to memorize.

Keybind	Action
prefix + Space	Open which-key menu

prefix + Space is intentionally given to which-key. Next-layout is still available via prefix + Alt+1–5.

jaclu/tmux-menus

Contextual popup menus for sessions, windows, panes, and settings.

Keybind	Action
prefix + g	Open context menu

Uses prefix + g — avoids conflict with prefix + M (clear mark) and prefix + \ (pain-control split).

---

Theme

2KAbhishek/tmux2k

Feature-rich status bar with widgets and multiple themes.

Configured layout:

Position	Widgets
Left	git · cwd · docker · mise
Right	cpu · ram · network · time

Theme: onedark with powerline separators (, ).

---

Key Conflict Resolution

tmux has many built-in keybinds. The table below shows every conflict found and how it is resolved in tmux.conf.

Key	tmux default	Plugin	Resolution
prefix + f	find-window	tmux-fastcopy	Fastcopy moved to prefix + F — default preserved
prefix + o	rotate-pane	tmux-sessionx	Sessionx moved to prefix + S — default preserved
prefix + l	last-window	tmux-pain-control	Default restored with bind-key l last-window after TPM loads
prefix + -	delete-buffer	tmux-pain-control	Pain-control overrides with split-h — accepted (rarely used default)
prefix + \	(pain-control split)	tmux-menus	Menus moved to prefix + g — pain-control split preserved
prefix + M	select-pane -M (clear mark)	tmux-menus	Menus moved to prefix + g — default preserved
prefix + Space	next-layout	tmux-which-key	which-key takes Space — next-layout still available via prefix + Alt+1–5