.dotfiles

tmux Reference

Terminal multiplexer for session management

Quick Start

# Start new session
tmux
tmux new -s project

# Attach to session
tmux attach
tmux a -t project

# List sessions
tmux ls

# Kill session
tmux kill-session -t project

Core Concepts

Hierarchy

Server
└── Session (workspace)
    └── Window (tab)
        └── Pane (split)

Prefix Key

All commands start with C-a (Ctrl+a)

Changed from default C-b for ergonomics.

Session Management

Command Action
tmux new -s name New named session
tmux a -t name Attach to session
tmux ls List sessions
tmux kill-session -t name Kill session
C-a d Detach from session
C-a s Session switcher
C-a $ Rename session

Window Management

Key Action
C-a c Create window
C-a , Rename window
C-a n Next window
C-a p Previous window
C-a l Last window
C-a 0-9 Go to window 0-9
C-a w Window list
C-a & Kill window

Pane Management

Creating Panes

Key Action
C-a | Split vertical
C-a - Split horizontal
C-a % Split vertical (default)
C-a " Split horizontal (default)
Key Action
C-a h/j/k/l Move to pane
C-h/j/k/l Smart navigation (with vim)
C-a o Cycle panes
C-a ; Last pane
C-a q Show pane numbers

Resizing

Key Action
C-a H/J/K/L Resize by 1
C-a M-h/j/k/l Resize by 5

Layout

Key Action
C-a Space Cycle layouts
C-a M-1 Even horizontal
C-a M-2 Even vertical
C-a M-3 Main horizontal
C-a M-4 Main vertical
C-a M-5 Tiled

Copy Mode

Entering

Key Action
C-a [ Enter copy mode
C-a PgUp Enter and scroll up
Key Action
h/j/k/l Move cursor
w/b Word forward/back
0/$ Line start/end
g/G Top/bottom
C-u/C-d Page up/down
/ Search forward
? Search backward
n/N Next/Previous result

Selection

Key Action
v Start selection
V Line selection
C-v Block selection
y Copy selection
Enter Copy and exit
Escape Clear selection
q Exit copy mode

Configuration

Location

~/.tmux.conf              # Main config
~/.config/tmux/           # Additional configs
  └── theme.conf         # Dynamic theme

Key Settings

# Prefix key
set -g prefix C-a

# Vi mode
setw -g mode-keys vi

# Mouse support
set -g mouse on

# Start windows at 1
set -g base-index 1

# Faster escape
set -sg escape-time 0

Workflows

Development Setup

# Create project session
tmux new -s myproject

# Split for editor and terminal
C-a |        # Vertical split
C-l          # Move right
C-a -        # Horizontal split

# Name windows
C-a c        # New window
C-a ,        # Rename to "server"
C-a c        # New window
C-a ,        # Rename to "logs"

Remote Work

# SSH and create session
ssh server
tmux new -s work

# Detach
C-a d

# Later, reattach
ssh server
tmux attach -t work

Advanced Features

Command Mode

C-a :        # Enter command mode

# Common commands
:new-window -n logs
:split-window -h
:resize-pane -R 10
:kill-pane
:source-file ~/.tmux.conf

Scripting

# Send commands
tmux send-keys -t session:window.pane "npm start" Enter

# Create complex layout
tmux new-session -d -s dev
tmux send-keys "vim" Enter
tmux split-window -h
tmux send-keys "npm run dev" Enter
tmux attach -t dev

Hooks

# In .tmux.conf
set-hook -g after-new-session 'run-shell "echo New session created"'
set-hook -g pane-focus-in 'run-shell "echo Pane focused"'

Integration

With Shell

# Aliases in .zshrc
alias ta='tmux attach'
alias tls='tmux ls'
alias tks='tmux kill-server'
alias tkss='tmux kill-session -t'

With Vim

" Seamless navigation
" C-h/j/k/l works in both
let g:tmux_navigator_no_mappings = 1
nnoremap <C-h> :TmuxNavigateLeft<cr>
nnoremap <C-j> :TmuxNavigateDown<cr>
nnoremap <C-k> :TmuxNavigateUp<cr>
nnoremap <C-l> :TmuxNavigateRight<cr>

With Git

# In tmux window
C-a c              # New window
C-a , lazygit      # Rename
lazygit            # Run lazygit

Tips and Tricks

Quick Commands

  1. Zoom pane: C-a z for focus
  2. Sync panes: C-a :setw synchronize-panes
  3. Monitor activity: C-a :setw monitor-activity on
  4. Break pane: C-a ! to new window

Productivity

  1. Named sessions: Always use descriptive names
  2. Window names: Name by purpose (editor, server, logs)
  3. Save layouts: Use tmuxinator for complex setups
  4. tmuxinator: Define project layouts

Display

  1. Clock: C-a t
  2. Pane info: C-a i
  3. Choose tree: C-a w for visual browser

Troubleshooting

Common Issues

Issue Solution
Colors wrong export TERM=screen-256color
Can’t create session tmux kill-server
Slow in vim set -sg escape-time 0
Copy not working Install reattach-to-user-namespace

Debug Commands

# Check server
tmux info

# List all settings
tmux show -g

# Check key bindings
tmux list-keys

# Reload config
tmux source ~/.tmux.conf

Status Line

Default Info

Width-responsive right side

The window tabs have priority. As the terminal narrows, the right-side system metrics drop in order so the tabs are never squeezed out, and the clock is always shown (static):

These are calibrated so a full-screen window shows everything and a half-width (~75 col) window collapses to just the clock; re-tune them to your own screen (tmux display -p '#{client_width}') as needed.

This is implemented with #{?#{e|>=:#{client_width},N},...,} conditionals in status-right (see src/tmux.conf and src/theme/templates/tmux.conf).

Three gotchas the implementation works around:

To re-tune the thresholds, edit the numbers in src/theme/templates/tmux.conf (and src/tmux.conf), then run src/theme/regenerate-all.sh and re-apply the theme. Use tmux display -p '#{client_width}' to read your current width.

Customization

# Simple
set -g status-left '#S '
set -g status-right '%H:%M '

Quick Reference Card

# Essential
C-a c      New window     C-a |     V-split
C-a n/p    Next/Prev      C-a -     H-split
C-a d      Detach         C-a z     Zoom
C-a [      Copy mode      C-a x     Kill pane

# Navigation
C-h/j/k/l  Move panes     C-a 0-9   Go to window
C-a o      Cycle panes    C-a w     Window list
C-a ;      Last pane      C-a s     Session list

# Advanced
C-a :      Command        C-a ?     List keys

← Back to Tools

This site is open source. Improve this page.