Skip to content

TMUX_GUIDE.md

Latest commit

 

History

History
500 lines (344 loc) · 10.6 KB

TMUX_GUIDE.md

File metadata and controls

500 lines (344 loc) · 10.6 KB
Raw

Tmux Beginner's Guide

A practical guide for terminal-savvy users new to tmux.

Table of Contents

  1. Core Concepts
  2. Getting Started
  3. The Prefix Key
  4. Common Operations
  5. Display Issues & Fixes
  6. Gotchas & Pain Points
  7. Copy/Paste (The Hard Part)
  8. Session Management
  9. Quick Reference

Core Concepts

Tmux has three levels of hierarchy:

Server
  └── Sessions (like desktop workspaces)
        └── Windows (like browser tabs)
              └── Panes (split views within a window)

Session: A collection of windows. You can detach from a session and it keeps running in the background. This is tmux's killer feature.

Window: Like a tab. Each window fills the whole terminal. You switch between them.

Pane: A split within a window. You can have multiple panes visible at once.

Getting Started

Starting tmux

# Start new session (anonymous)
tmux

# Start new session with a name (recommended)
tmux new -s myproject

# Start in a specific directory
tmux new -s myproject -c ~/code/myproject

Exiting tmux

There are two ways to leave tmux:

Action What Happens
Detach (` then d) Tmux keeps running in background. You can reattach later.
Exit (type exit or Ctrl+D) Closes the pane/window/session. If last pane, session ends.

Detach is usually what you want. Your processes keep running.

Reattaching

# List sessions
tmux ls

# Attach to most recent
tmux a

# Attach to specific session
tmux a -t myproject

# Attach to session, detaching other clients
tmux a -dt myproject

The Prefix Key

Almost all tmux commands start with a prefix key.

Your prefix is: ` (backtick)

Default tmux uses Ctrl+b, but this config changed it to backtick for easier access.

How prefix works

  1. Press backtick (`)
  2. Release it
  3. Press the command key

It's a sequence, not a chord. Think of it as "activating command mode."

` then d     = detach
` then c     = new window
` then v     = vertical split

Typing a literal backtick

Since backtick is the prefix, to type an actual ` character:

` then `     = types a backtick

Common Operations

Panes (Splits)

Keys Action
` v Split vertically (left/right)
` s Split horizontally (top/bottom)
Ctrl+h/j/k/l Move between panes (vim-style, no prefix needed)
` x Toggle zoom current pane (fullscreen)
` j Resize pane down
` k Resize pane up
exit or Ctrl+d Close current pane

Windows (Tabs)

Keys Action
` c Create new window
Alt+h or Alt+← Previous window
Alt+l or Alt+→ Next window
` 1-9 Jump to window by number
` , Rename current window

Sessions

Keys Action
` d Detach from session
` w Session/window picker (interactive)
` $ Rename session
` N Create new worktree session

Display Issues & Fixes

Screen looks corrupted/garbled

This happens when programs output garbage or terminal gets confused.

# Inside tmux - refresh the display
# Press: ` then r

# Or run this command
tmux refresh-client

# Nuclear option - reset terminal
reset

Panes are wrong size / overlapping

Usually happens when you resize your terminal window while detached.

# Detach and reattach
# Press: ` then d
tmux a

# Or force resize
tmux refresh-client -S

Status bar missing or corrupt

# Reload config
# Press: ` then R

# Or manually
tmux source-file ~/.tmux.conf

Colors look wrong

Check your TERM variable:

echo $TERM
# Should be: xterm-256color or screen-256color

If wrong, add to your ~/.bashrc or ~/.zshrc:

export TERM=xterm-256color

"Terminal too small" or content cut off

Tmux remembers the smallest attached client size. If you have multiple terminals attached to the same session:

# Detach other clients
tmux detach -a

# Or attach exclusively
tmux a -d

Gotchas & Pain Points

1. "I pressed the prefix but nothing happened"

  • Make sure you release the prefix before pressing the next key
  • Commands are case-sensitive: D ≠ d
  • Check that config is loaded: ` then R

2. "My shell history/scrollback is gone"

Tmux has its own scrollback buffer, separate from your terminal's.

To scroll in tmux:

  • PageUp - enters copy mode and scrolls up
  • In copy mode: j/k to scroll, q to exit

Or enable mouse mode (already enabled in this config):

  • Just scroll with your mouse/trackpad

3. "Ctrl+L doesn't clear the screen properly"

Tmux intercepts some keys. Use:

# Clear screen AND scrollback
Alt+u

# Or just clear (keeps scrollback)
clear

4. "My vim/neovim colors are wrong inside tmux"

Add to your .vimrc or init.vim:

set termguicolors
set background=dark

And ensure TERM is set correctly (see Display Issues above).

5. "I can't scroll with my mouse"

Mouse mode is enabled in this config. But if it's not working:

# Check mouse setting
tmux show -g mouse
# Should output: mouse on

# Enable it manually
tmux set -g mouse on

6. "Commands I run keep stopping when I detach"

They shouldn't! This is tmux's main feature. But watch out for:

  • Programs that detect no TTY and exit
  • SSH sessions timing out (separate from tmux)
  • Running exit instead of detaching

Always detach (` then d) instead of closing the terminal.

7. "I accidentally closed my session"

If you have tmux-resurrect plugin installed:

` then Ctrl+r    = restore last saved session

Sessions auto-save every 15 minutes with tmux-continuum.

8. "Split panes don't preserve my current directory"

This config fixes that. But if it's not working, check the config has:

bind v split-window -h -c "#{pane_current_path}"
bind s split-window -v -c "#{pane_current_path}"

9. "I want to run something in a pane and switch away"

Just switch panes/windows - everything keeps running. That's the point!

# Start long-running command
yarn test --watch

# Press Ctrl+h/j/k/l to move to another pane
# Or Alt+l to go to next window

10. "ESC key has a delay in vim"

Fixed in this config with escape-time 0. If you still see delay:

# Check current setting
tmux show -g escape-time
# Should be: 0

Copy/Paste (The Hard Part)

This is tmux's most confusing feature. There are multiple clipboard systems interacting.

The Simple Way (Mouse)

With mouse mode enabled:

  1. Hold Shift while selecting text with mouse
  2. Normal terminal copy (Ctrl+Shift+C or Cmd+C)
  3. Normal paste (Ctrl+Shift+V or Cmd+V)

Holding Shift bypasses tmux and lets your terminal handle it.

The Tmux Way (Keyboard)

  1. Enter copy mode: PageUp or ` then [
  2. Navigate with vim keys (hjkl, Ctrl+u/d for page up/down)
  3. Start selection: Space
  4. Move to end of selection: vim motions
  5. Copy: Enter
  6. Paste: ` then ]

This uses tmux's internal clipboard (paste buffer).

Copy to System Clipboard

To make tmux copy to your system clipboard, you need additional setup depending on your OS. This config doesn't include it by default.

For Linux (X11):

# Add to ~/.tmux.conf
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -sel clip"

For macOS:

bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"

Session Management

Naming conventions

Good session names = easier management:

tmux new -s project-api      # By project
tmux new -s feat-auth        # By feature/branch
tmux new -s client-acme      # By client

Multiple sessions workflow

# Create sessions for different contexts
tmux new -s main -d           # -d = detached (don't attach yet)
tmux new -s api -d
tmux new -s frontend -d

# List them
tmux ls

# Switch between (inside tmux)
# Press: ` then w   (interactive picker)
# Or: ` then s      (tree view)

Session persistence

This config includes plugins for session persistence:

Plugin What it does
tmux-resurrect Manual save/restore
tmux-continuum Auto-save every 15 min

Commands:

` then Ctrl+s    = Save session
` then Ctrl+r    = Restore session

What's saved:

  • Window/pane layouts
  • Working directories
  • Running programs (basic)
  • Vim sessions (if configured)

What's NOT saved:

  • Shell history in panes
  • Environment variables
  • Complex program state

Quick Reference

Essential Commands (Memorize These)

Keys Action
` d Detach (most important!)
` c New window
` v Split vertical
` s Split horizontal
Ctrl+h/j/k/l Move between panes
Alt+h/l Previous/next window
` w Session picker
` R Reload config
PageUp Scroll mode

Command Line

tmux                    # Start new session
tmux new -s NAME        # Start named session
tmux ls                 # List sessions
tmux a                  # Attach to last session
tmux a -t NAME          # Attach to named session
tmux kill-session -t X  # Kill session
tmux kill-server        # Kill everything

Layouts (Custom to this config)

Keys Layout
` D Dev: Editor 60% | Terminal stack
` T Test: Editor 70% | Runner 30%
` W 4 equal panes (worktree overview)

Getting Help

# Show all keybindings
tmux list-keys

# Show all keybindings with prefix
tmux list-keys | grep "prefix"

# Show specific setting
tmux show -g <option>

# Custom help script (this config)
~/.tmux/scripts/tmux-help.sh

Inside tmux: ` then ? shows keybindings (press q to exit).

Files in This Setup

~/.tmux.conf                              # Main config
~/.tmux/plugins/                          # TPM plugins
~/.tmux/layouts/                          # Custom layouts
~/.tmux/scripts/                          # Helper scripts
~/.tmux/resurrect/                        # Session saves (auto-created)

Next Steps

  1. Practice detach/attach - This is the core workflow
  2. Learn pane navigation - Ctrl+hjkl becomes muscle memory
  3. Use named sessions - tmux new -s projectname
  4. Install plugins - Press ` then I (capital i)
  5. Try the layouts - ` then D for dev layout