Iterm2

Iterm2

Complete reference for iTerm2 terminal emulator and tmux terminal multiplexer on macOS. Covers keyboard shortcuts, configuration, tmux integration, and productivity workflows.

Workflow Routing

When executing a workflow, do BOTH of these:

1. Call the notification script (for observability tracking):

   ~/.claude/Tools/SkillWorkflowNotification WORKFLOWNAME Iterm2

2. Output the text notification (for user visibility):

   Running the **WorkflowName** workflow from the **Iterm2** skill...

Examples

Example 1: Split terminal into multiple panes

User: "How do I split my terminal in iTerm2?"
→ References Shortcuts.md
→ Explains Cmd+D (vertical) and Cmd+Shift+D (horizontal)
→ Shows navigation with Cmd+Option+Arrow

Example 2: Setup tmux with iTerm2 integration

User: "How do I use tmux with iTerm2?"
→ Invokes SetupTmux workflow
→ Explains tmux -CC control mode
→ Shows native window integration benefits

Example 3: Manage persistent sessions over SSH

User: "Keep my terminal running after disconnect"
→ Invokes TmuxSession workflow
→ Creates named session with tmux new -s
→ Shows how to reattach after disconnect

Quick Reference

iTerm2 Essentials

tmux Essentials

Default prefix: Ctrl+b

iTerm2 + tmux Integration

Run tmux -CC for native iTerm2 integration:

• tmux windows appear as native iTerm2 windows
• Use iTerm2 shortcuts instead of tmux prefix
• Sessions persist through disconnects
• Dashboard available via Shell > tmux > Dashboard

Documentation Index

---

Gotchas

• "Reuse previous session's directory" is per-profile and per-context: New windows from Cmd-N use the profile's window setting; new tabs from Cmd-T use the tab setting. They differ — confusing when prompts open in unexpected directories.
• `tmux -CC` requires the tmux server to be installed and started: If tmux is on a remote host but iTerm2 is local, tmux -CC attach works over SSH only when SSH was started from iTerm2 itself — not from a script that spawns a subshell.
• Cmd-D split uses the current pane's profile, NOT the window default: Once a profile changes mid-session (via shell integration), new splits inherit the modified profile and can carry unwanted env or PATH.
• `Ctrl+b` prefix conflicts with readline `transpose-words`: Vi-mode users who rebind it (set -g prefix C-a) must remember Ctrl+a also conflicts with screen and shell line-start — pick a free combo like C-Space.
• Shell integration injects OSC 1337 escape codes: Pipelines that capture terminal output (script, asciinema) end up with garbled control sequences unless integration is disabled per-pane via Edit Session > Disable Shell Integration.
• Status bar updates run on the main thread: Heavy custom status bar scripts (long git status, slow cloud CLIs) freeze the entire terminal — keep status callbacks under 100ms or run them async.

Keyboard Shortcuts Reference

Complete keyboard shortcuts for iTerm2 and tmux.

iTerm2 Shortcuts

Window & Tab Management

Split Panes

Search & Selection

Shell Integration

Utilities

Text Manipulation

tmux Shortcuts

Default prefix key: Ctrl+b

Sessions

Windows

Panes

Copy Mode (vi keys)

Miscellaneous

iTerm2 tmux Integration Mode

When running tmux -CC:

Pro Tip: In tmux integration mode, use native iTerm2 shortcuts instead of tmux prefix shortcuts.

tmux Command Reference

Complete reference for tmux terminal multiplexer commands.

Session Management

Creating Sessions

# New session (auto-named)
tmux
tmux new
tmux new-session

# New named session
tmux new -s mysession

# New session with window name
tmux new -s mysession -n mywindow

# New session detached
tmux new -s mysession -d

# New session, attach if exists
tmux new-session -A -s mysession

Attaching to Sessions

# Attach to last session
tmux attach
tmux a

# Attach to named session
tmux attach -t mysession
tmux a -t mysession

# Attach, detach other clients
tmux attach -dt mysession

# Attach read-only
tmux attach -r -t mysession

Listing & Killing Sessions

# List all sessions
tmux ls
tmux list-sessions

# Kill specific session
tmux kill-session -t mysession

# Kill all sessions except current
tmux kill-session -a

# Kill all sessions except named
tmux kill-session -a -t mysession

# Kill entire server
tmux kill-server

Renaming Sessions

# From command line
tmux rename-session -t old_name new_name

# From within tmux (prefix then $)
Ctrl+b $

Window Management

Creating Windows

# New window (from within tmux)
Ctrl+b c

# New window via command
tmux new-window

# New window with name
tmux new-window -n mywindow

# New window in background
tmux new-window -d -n mywindow

Navigating Windows

# List all windows
Ctrl+b w

# Next window
Ctrl+b n

# Previous window
Ctrl+b p

# Go to window by number
Ctrl+b 0-9

# Last active window
Ctrl+b l

# Find window by name
Ctrl+b f

Managing Windows

# Rename current window
Ctrl+b ,

# Kill current window
Ctrl+b &

# Swap windows
tmux swap-window -s 2 -t 1

# Move window to index
tmux move-window -t 3

# Renumber all windows
tmux move-window -r

Pane Management

Splitting Panes

# Split vertical (side by side)
Ctrl+b %
tmux split-window -h

# Split horizontal (top/bottom)
Ctrl+b "
tmux split-window -v

# Split with specific size (percentage)
tmux split-window -h -p 30

# Split with specific size (cells)
tmux split-window -v -l 10

Navigating Panes

# Move between panes
Ctrl+b Arrow

# Next pane
Ctrl+b o

# Previous pane
Ctrl+b ;

# Show pane numbers (then press number)
Ctrl+b q

# Jump to pane by number
Ctrl+b q 0-9

Resizing Panes

# Resize (hold Ctrl)
Ctrl+b Ctrl+Arrow

# Resize by specific amount
tmux resize-pane -D 10  # Down
tmux resize-pane -U 10  # Up
tmux resize-pane -L 10  # Left
tmux resize-pane -R 10  # Right

# Resize to percentage
tmux resize-pane -x 50%
tmux resize-pane -y 30%

# Toggle zoom (full window)
Ctrl+b z

Managing Panes

# Close pane
Ctrl+b x

# Convert pane to window
Ctrl+b !

# Swap panes
Ctrl+b }  # Swap with next
Ctrl+b {  # Swap with previous

# Join pane from another window
tmux join-pane -s :2.0 -t :1

# Send pane to another window
tmux join-pane -t :2

# Rotate panes
Ctrl+b Ctrl+o  # Rotate forward
Ctrl+b Alt+o   # Rotate backward

# Apply layouts
Ctrl+b Space        # Cycle through layouts
Ctrl+b Alt+1-5      # Apply specific layout

Layout Presets

Copy Mode

Entering Copy Mode

# Enter copy mode
Ctrl+b [

# Scroll up in copy mode
PageUp or Ctrl+b PageUp

Navigation (vi mode)

Selection & Copy

# Start selection
Space

# Copy selection (exits copy mode)
Enter

# Paste buffer
Ctrl+b ]

# List buffers
tmux list-buffers

# Save buffer to file
tmux save-buffer ~/buffer.txt

# Load file to buffer
tmux load-buffer ~/file.txt

Configuration

Common tmux.conf Settings

# Change prefix from Ctrl+b to Ctrl+a
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# Enable mouse support
set -g mouse on

# Use vi keys in copy mode
setw -g mode-keys vi

# Start window numbering at 1
set -g base-index 1
setw -g pane-base-index 1

# Renumber windows on close
set -g renumber-windows on

# Increase history limit
set -g history-limit 10000

# Enable 256 colors
set -g default-terminal "screen-256color"

# Faster escape time
set -sg escape-time 0

# Enable focus events
set -g focus-events on

# Aggressive resize
setw -g aggressive-resize on

Key Binding Examples

# Reload config with r
bind r source-file ~/.tmux.conf \; display "Config reloaded!"

# Split panes using | and -
bind | split-window -h
bind - split-window -v

# Vim-style pane navigation
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Resize panes with vim keys
bind -r H resize-pane -L 5
bind -r J resize-pane -D 5
bind -r K resize-pane -U 5
bind -r L resize-pane -R 5

Applying Configuration

# Reload from within tmux
Ctrl+b :source-file ~/.tmux.conf

# Or with bound key (after adding bind above)
Ctrl+b r

# From command line
tmux source-file ~/.tmux.conf

Scripting & Automation

Running Commands in Sessions

# Send keys to a session
tmux send-keys -t mysession "echo hello" Enter

# Run command in new window
tmux new-window "htop"

# Run command in new session
tmux new-session -d -s work "vim"

# Execute command and wait
tmux run-shell "sleep 5 && echo done"

Environment Variables

# Set environment variable
tmux set-environment MY_VAR "value"

# Get environment variable
tmux show-environment MY_VAR

# Update from shell environment
tmux set-environment -g MY_VAR "$MY_VAR"

Display Messages

# Show message
tmux display-message "Hello World"

# Show for specific duration
tmux display-message -d 5000 "5 second message"

tmux Configuration Guide

Complete guide to configuring tmux via ~/.tmux.conf.

Configuration File Location

tmux reads configuration from: 1. /etc/tmux.conf (system-wide) 2. ~/.tmux.conf (user) 3. ~/.config/tmux/tmux.conf (XDG)

Create if it doesn't exist:

touch ~/.tmux.conf

Essential Configuration

Recommended Starter Config

# ~/.tmux.conf - Essential tmux configuration

# ---------- General Settings ----------

# Use 256 colors and true color
set -g default-terminal "screen-256color"
set -sa terminal-overrides ",xterm*:Tc"

# Enable mouse support
set -g mouse on

# Increase history limit
set -g history-limit 50000

# Start window numbering at 1
set -g base-index 1
setw -g pane-base-index 1

# Renumber windows when one is closed
set -g renumber-windows on

# Faster escape time (for vim)
set -sg escape-time 0

# Enable focus events for vim
set -g focus-events on

# Use vi mode in copy mode
setw -g mode-keys vi

# Automatically rename windows
setw -g automatic-rename on

# ---------- Key Bindings ----------

# Change prefix to Ctrl+a (optional)
# set -g prefix C-a
# unbind C-b
# bind C-a send-prefix

# Reload config with prefix + r
bind r source-file ~/.tmux.conf \; display "Config reloaded!"

# Split panes with | and -
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
bind '"' split-window -v -c "#{pane_current_path}"
bind % split-window -h -c "#{pane_current_path}"

# New window in current path
bind c new-window -c "#{pane_current_path}"

# Vim-style pane navigation
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Resize panes with vim keys
bind -r H resize-pane -L 5
bind -r J resize-pane -D 5
bind -r K resize-pane -U 5
bind -r L resize-pane -R 5

# Quick pane switching with Alt+arrow
bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up select-pane -U
bind -n M-Down select-pane -D

# Copy mode improvements
bind -T copy-mode-vi v send -X begin-selection
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"
bind -T copy-mode-vi Enter send -X copy-pipe-and-cancel "pbcopy"

# ---------- Status Bar ----------

set -g status-position bottom
set -g status-interval 1
set -g status-style bg=black,fg=white

# Left status
set -g status-left-length 30
set -g status-left '#[fg=green]#S '

# Right status
set -g status-right-length 60
set -g status-right '#[fg=yellow]%H:%M:%S #[fg=green]%d-%b-%y'

# Window status
setw -g window-status-current-style fg=black,bg=green
setw -g window-status-format ' #I:#W '
setw -g window-status-current-format ' #I:#W '

Configuration Options Reference

Server Options (set -s)

Session Options (set -g)

Window Options (setw -g)

Key Binding Syntax

Basic Binding

# bind KEY command
bind r source-file ~/.tmux.conf

Binding with Flags

# -r: repeatable (hold prefix, tap key multiple times)
bind -r H resize-pane -L 5

# -n: no prefix required
bind -n M-Left select-pane -L

# -T: specify key table
bind -T copy-mode-vi v send -X begin-selection

Unbinding Keys

# Remove a binding
unbind C-b

# Remove all bindings in table
unbind -a -T prefix

Status Bar Configuration

Format Variables

Style Attributes

# Colors
fg=colour231    # Foreground (0-255 or named)
bg=colour234    # Background

# Named colors
fg=black,red,green,yellow,blue,magenta,cyan,white

# Attributes
bold,dim,underscore,blink,reverse,hidden,italics

# Combined
set -g status-style bg=black,fg=white,bold

Status Bar Components

# Left side
set -g status-left-length 50
set -g status-left '#[fg=green,bold]#S #[fg=white]| '

# Right side
set -g status-right-length 100
set -g status-right '#[fg=cyan]#(whoami)@#H #[fg=yellow]%Y-%m-%d %H:%M'

# Window format
setw -g window-status-format '#I:#W#F'
setw -g window-status-current-format '#[fg=green,bold]#I:#W#F'

Hooks

Run commands on events:

# After creating new session
set-hook -g after-new-session 'run-shell "echo session created"'

# After creating new window
set-hook -g after-new-window 'rename-window "new"'

# After client attached
set-hook -g client-attached 'display-message "Welcome!"'

Plugin Management (TPM)

Installing TPM

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

Configuration

# List of plugins
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'

# Initialize TPM (keep at bottom)
run '~/.tmux/plugins/tpm/tpm'

Popular Plugins

TPM Commands

iTerm2 Integration

For iTerm2 tmux control mode:

# Recommended settings for iTerm2 integration
set -g assume-paste-time 0
set -g focus-events on

# Note: When using tmux -CC, you use iTerm2's
# native shortcuts instead of tmux bindings

Run with: tmux -CC or tmux -CC attach

Troubleshooting

Colors Not Working

# Check terminal
echo $TERM

# In tmux.conf
set -g default-terminal "screen-256color"
set -sa terminal-overrides ",*256col*:Tc"

Slow Escape Key

# Reduce escape time (default is 500ms)
set -sg escape-time 10

Mouse Not Working

# Enable mouse
set -g mouse on

Reload Config

# From within tmux
tmux source-file ~/.tmux.conf

# Or if you have the binding
Ctrl+b r

SetupTmux Workflow

Setup and configure tmux for optimal iTerm2 integration.

Prerequisites

• iTerm2 installed on macOS
• tmux installed (brew install tmux)

Steps

1. Verify Installation

# Check tmux is installed
which tmux
tmux -V

# If not installed
brew install tmux

2. Create Configuration File

Create ~/.tmux.conf with recommended settings:

# Essential settings for iTerm2 integration
set -g default-terminal "screen-256color"
set -sa terminal-overrides ",xterm*:Tc"
set -g mouse on
set -g history-limit 50000
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on
set -sg escape-time 0
set -g focus-events on
setw -g mode-keys vi

# Reload config binding
bind r source-file ~/.tmux.conf \; display "Reloaded!"

# Better splits
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

# Vim-style navigation
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Copy to macOS clipboard
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"

3. Choose Integration Mode

Option A: Native tmux (traditional)

tmux new -s main

• Use tmux shortcuts (Ctrl+b prefix)
• Works in any terminal
• Full tmux feature set

Option B: iTerm2 Integration Mode (recommended)

tmux -CC

• tmux windows appear as native iTerm2 tabs/windows
• Use iTerm2 shortcuts (Cmd-based)
• Sessions persist through SSH disconnects
• Best of both worlds

4. Test the Setup

# Start integrated session
tmux -CC

# Create windows and panes using iTerm2 shortcuts:
# Cmd+D for vertical split
# Cmd+Shift+D for horizontal split
# Cmd+T for new tab

# Detach with Esc or Shell > tmux > Detach

# Reattach
tmux -CC attach

5. Optional: Install TPM (Plugin Manager)

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

Add to ~/.tmux.conf:

set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-resurrect'

run '~/.tmux/plugins/tpm/tpm'

Install plugins: Ctrl+b I

Verification

1. Open iTerm2 2. Run tmux -CC 3. Verify native window integration works 4. Test Cmd+D and Cmd+Shift+D for splits 5. Detach with Esc 6. Verify tmux ls shows session 7. Reattach with tmux -CC attach

Common Issues

tmux not found:

brew install tmux

Integration mode not working:

• Ensure iTerm2 is up to date
• Check Settings > General > tmux

Colors look wrong:

# Add to .tmux.conf
set -g default-terminal "screen-256color"
set -sa terminal-overrides ",xterm*:Tc"

TmuxSession Workflow

Manage tmux sessions for persistent terminal work.

Use Cases

• Keep processes running after terminal close
• Maintain work context across SSH disconnects
• Organize multiple projects in separate sessions

Session Operations

Create New Session

Named session (recommended):

# Standard tmux
tmux new -s projectname

# iTerm2 integration mode
tmux -CC new -s projectname

With initial command:

tmux new -s dev -n editor "vim"

List Sessions

# From command line
tmux ls

# From within tmux
Ctrl+b s  # Interactive session list

Attach to Session

# Standard tmux
tmux attach -t projectname
tmux a -t projectname  # Short form

# iTerm2 integration mode
tmux -CC attach -t projectname

# Attach to most recent
tmux attach
tmux -CC attach

Detach from Session

Standard tmux:

• Ctrl+b d

iTerm2 integration:

• Press Esc
• Or Shell > tmux > Detach

Switch Between Sessions

From within tmux:

• Ctrl+b s - Interactive session list
• Ctrl+b ( - Previous session
• Ctrl+b ) - Next session

Rename Session

# From command line
tmux rename-session -t old_name new_name

# From within session
Ctrl+b $

Kill Session

# Specific session
tmux kill-session -t projectname

# All except current
tmux kill-session -a

# All sessions
tmux kill-server

Session Workflows

Project-Based Sessions

Create dedicated sessions per project:

# Work projects
tmux new -s work-api
tmux new -s work-frontend
tmux new -s work-docs

# Personal
tmux new -s dotfiles
tmux new -s learning

# List all
tmux ls

Multi-Window Session Setup

# Create session with first window
tmux new -s myproject -n editor -d

# Add more windows
tmux new-window -t myproject -n server
tmux new-window -t myproject -n logs

# Attach to it
tmux attach -t myproject

SSH Persistent Sessions

For remote work that survives disconnects:

# On remote server
ssh myserver

# Create or attach to session
tmux new -A -s main

# Do your work...

# Disconnect (Ctrl+b d or close terminal)
# Session keeps running

# Reconnect later
ssh myserver
tmux attach -t main
# You're right where you left off

iTerm2 Integration for SSH

Important: tmux -CC integration mode only works when tmux runs locally on your Mac. For remote servers, use standard tmux mode.

# LOCAL machine - can use integration mode
tmux -CC

# REMOTE server - use standard tmux
ssh myserver
tmux new -s main      # Standard mode, not -CC

# Why? The -CC protocol requires iTerm2 to communicate
# directly with tmux. Over SSH, use standard tmux shortcuts.

Hybrid approach for persistent remote work:

# SSH to server
ssh myserver

# Use standard tmux on remote
tmux new -A -s main

# Your session persists across:
# - SSH disconnects
# - Network changes
# - Terminal crashes

# Reconnect later
ssh myserver
tmux attach -t main
# You're right where you left off

Best Practices

1. Always name sessions - Makes management easier 2. Use integration mode - tmux -CC for best iTerm2 experience 3. Detach, don't quit - Session survives for later 4. One session per project - Clean context switching 5. Regular cleanup - Kill unused sessions

Quick Reference

TroubleshootTmux Workflow

Diagnose and fix common tmux and iTerm2 integration issues.

Diagnostic Commands

Run these first to understand the environment:

# tmux version
tmux -V

# List running sessions
tmux ls

# Check tmux server
tmux info

# Check config syntax
tmux source-file ~/.tmux.conf

Common Issues

tmux Command Not Found

Symptom: command not found: tmux

Fix:

# Install with Homebrew
brew install tmux

# Verify
which tmux
tmux -V

Sessions Not Persisting

Symptom: Session disappears after terminal close

Causes: 1. Running tmux without detaching first 2. tmux server killed 3. Running in non-session mode

Fix:

# Always detach properly
Ctrl+b d

# Or for iTerm2 integration
Press Esc

# Verify session exists
tmux ls

# Don't use `exit` in last pane - it kills session

iTerm2 Integration Not Working

Symptom: tmux -CC doesn't create native windows

Fixes:

1. Update iTerm2:

# Check version
iTerm2 > About iTerm2
# Should be 3.0+ for tmux integration

2. Check tmux integration settings:

• iTerm2 > Settings > General > tmux
• Enable integration features

3. Reset integration:

# Kill all tmux sessions
tmux kill-server

# Restart iTerm2
# Try again
tmux -CC

Colors Wrong or Missing

Symptom: Colors don't display correctly, vim looks wrong

Fix:

# Add to ~/.tmux.conf
set -g default-terminal "screen-256color"
set -sa terminal-overrides ",xterm*:Tc"

# Reload
tmux source-file ~/.tmux.conf

# Or set TERM in shell
export TERM=screen-256color

Slow Escape Key

Symptom: Delay after pressing Escape (affects vim)

Fix:

# Add to ~/.tmux.conf
set -sg escape-time 10  # or 0

# Reload
tmux source-file ~/.tmux.conf

Mouse Not Working

Symptom: Can't click or scroll with mouse

Fix:

# Add to ~/.tmux.conf
set -g mouse on

# Reload
tmux source-file ~/.tmux.conf

Copy/Paste Not Working

Symptom: Can't copy text to system clipboard

Fix for macOS:

# Add to ~/.tmux.conf
set -g mouse on
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"
bind -T copy-mode-vi Enter send -X copy-pipe-and-cancel "pbcopy"

# Enter copy mode
Ctrl+b [

# Select with mouse or Space to start, Enter to copy
# Paste normally with Cmd+V

Config Changes Not Applied

Symptom: Changes to .tmux.conf don't take effect

Fix:

# Method 1: Reload from tmux command mode
Ctrl+b :source-file ~/.tmux.conf

# Method 2: If you have the binding
Ctrl+b r

# Method 3: Kill and restart
tmux kill-server
tmux new -s fresh

"Terminal is not fully functional"

Symptom: Warning messages about terminal capabilities

Fix:

# Set correct TERM
export TERM=xterm-256color

# In .tmux.conf
set -g default-terminal "screen-256color"

Panes Not Resizing Properly

Symptom: Split panes have wrong dimensions

Fix:

# Enable aggressive resize
setw -g aggressive-resize on

# Detach other clients
tmux attach -d

Can't Detach (Integration Mode)

Symptom: Pressing Esc doesn't detach in iTerm2

Fixes:

1. Try pressing Esc multiple times 2. Use tmux Dashboard: Shell > tmux > Dashboard > Detach 3. Force quit: Press X in integration menu 4. Run in terminal: tmux detach

If completely stuck:

# Kill the integration client
tmux kill-session -t 0

# Or kill server
tmux kill-server

"sessions should be nested with care"

Symptom: Warning when running tmux inside tmux

Explanation: You're trying to start tmux inside an existing session

Fix:

# Check if already in tmux
echo $TMUX

# If set, you're already in tmux
# Create new window instead
Ctrl+b c

# Or new session in background
tmux new -d -s another

Recovery Commands

Stuck Terminal

# Reset terminal
stty sane
reset

Frozen tmux

# From another terminal
tmux kill-server

# Or kill specific session
tmux kill-session -t stuck_session

Clean Restart

# Kill everything
tmux kill-server

# Remove socket (if corrupted)
rm -rf /tmp/tmux-$(id -u)

# Fresh start
tmux new -s fresh

Debug Mode

Enable logging for bug reports:

# In iTerm2 integration mode
Press L to toggle logging

# Logs go to /tmp/tmux-*.log

# For tmux itself
tmux -vvv new -s debug
# Creates tmux-*.log files

Getting Help

# tmux manual
man tmux

# List all key bindings
tmux list-keys

# Show all options
tmux show-options -g
tmux show-options -gw

# Check running config
tmux show-options -s