Essential reference for Emacs — keybindings, buffers, windows, org-mode, packages, and init configuration.

Tmux Nested Scrolling Cheat Sheet

A practical guide to scrolling in tmux sessions — especially when running tmux inside tmux. Includes mouse support, keyboard shortcuts, copy-mode, and prefix handling for multi-level navigation.

⚠️ The Nested Tmux Problem

Nested tmux is a special challenge — when you run tmux inside tmux, the scrollback handling becomes a battle between two competing terminal multiplexers. By default:

• Prefix + Scroll → Outer tmux captures the action (inner session ignored)
• Mouse Wheel → May scroll outer session instead of inner pane
• Copy-mode → Requires escaping through multiple layers
• Alt-keys → Often not passed through correctly

Why this matters: Nested tmux isn't just a curiosity — it's a critical workflow for:

• Remote development: SSH into a server → tmux → nested tmux for isolated projects
• Multi-environment work: Different tmux sessions for dev, staging, production
• Team collaboration: Screen sharing with nested sessions for different contexts
• Container workflows: Host tmux → container tmux for microservice debugging
• CI/CD pipelines: Build servers with nested session hierarchies

Without proper configuration, you lose access to the inner session's scrollback — the very thing you need when debugging or reviewing output.

Quick Reference: Scroll Bindings

Configuration: ~/.tmux.conf

# =============================================================================
# PREFIX KEY (change from Ctrl+B to Ctrl+A)
# =============================================================================
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# =============================================================================
# MOUSE SUPPORT (recommended)
# =============================================================================
set -g mouse on

# Direct mouse scroll in panes
bind-key -n MouseWheelUpPane send-keys -X scroll-up
bind-key -n MouseWheelDownPane send-keys -X scroll-down

# =============================================================================
# ALT-KEY SCROLLING (no prefix needed)
# =============================================================================
bind-key -n M-Up send-keys -X scroll-up
bind-key -n M-Down send-keys -X scroll-down
bind-key -n M-PageUp send-keys -X scroll-up
bind-key -n M-PageDown send-keys -X scroll-down

# Open copy-mode with Alt+Space
bind-key -n M-Space copy-mode

# =============================================================================
# VI-STYLE COPY-MODE
# =============================================================================
set-window-option -g mode-keys vi

# Copy-mode navigation
bind-key v copy-mode
bind-key -T copy-mode-vi k send-keys -X cursor-up
bind-key -T copy-mode-vi j send-keys -X cursor-down
bind-key -T copy-mode-vi h send-keys -X cursor-left
bind-key -T copy-mode-vi l send-keys -X cursor-right
bind-key -T copy-mode-vi Space start-selection
bind-key -T copy-mode-vi Enter copy-pipe-and-cancel "xclip -selection clipboard"

# =============================================================================
# NESTED TMUX HANDLING
# =============================================================================
# Double prefix for nested sessions
set -g prefix2 C-a

# Extended keys for better scroll support
set -g extended-keys on

# =============================================================================
# PANE NAVIGATION (bonus)
# =============================================================================
bind-key -n M-H select-pane -L
bind-key -n M-J select-pane -D
bind-key -n M-K select-pane -U
bind-key -n M-L select-pane -R

# =============================================================================
# WINDOW NAVIGATION (bonus)
# =============================================================================
bind-key -n M-Left previous-window
bind-key -n M-Right next-window

# =============================================================================
# GENERAL SETTINGS
# =============================================================================
set -g default-terminal "screen-256color"
set -g history-limit 10000
set -g status-interval 5

Apply Configuration

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

# Or from within tmux: Prefix + :
# Then type: source-file ~/.tmux.conf

Copy-Mode Navigation (Vi-Style)

Once in copy-mode (via Alt+Space or Prefix + [):

Nested Tmux Workflows

Scenario 1: Quick Scroll (Inner Session)

Inner tmux: Mouse wheel or Alt+↑/↓

Scenario 2: Navigate Outer Session

Outer tmux: Prefix (C-a) then scroll keys

Scenario 3: Copy from Inner to Clipboard

1. Alt+Space (enter copy-mode in inner)
2. Navigate with hjkl
3. Space to select
4. Enter to copy

Scenario 4: Switch Between Nested Sessions

Prefix + Prefix (C-a C-a) → switches to outer

Common Issues & Solutions

Issue: Mouse scroll doesn't work

Solution: Ensure set -g mouse on is in your config

Issue: Alt-keys send escape sequences

Solution: Add set -g escape-time 0 and ensure terminal supports meta keys

Issue: Can't escape nested tmux

Solution: Use Prefix + Prefix (C-a C-a) to reach outer session

Issue: Scroll history too short

Solution: Increase with set -g history-limit 10000 (or higher)

Deployment via Ansible

To deploy this configuration across multiple hosts:

# ansible/roles/tmux/tasks/main.yml
- name: Deploy tmux configuration
  copy:
    src: files/tmux.conf
    dest: ~/.tmux.conf
    owner: "{{ ansible_user_id }}"
    mode: "0644"
  notify: reload tmux

- name: Ensure tmux is reloaded
  command: tmux source-file ~/.tmux.conf
  ignore_errors: yes

Quick Test

After applying the config, test with:

# 1. Start tmux
tmux

# 2. Test mouse scroll (should work immediately)

# 3. Test Alt+Up/Down (scrolls history)

# 4. Test Alt+Space (opens copy-mode)

# 5. Create nested session
tmux

# 6. Test nested scroll (Alt-keys work in inner, C-a C-a for outer)

Related Resources

• Tmux Manual
• Tmux GitHub
• Vi Mode Reference

Version Info

• tmux version: 2.8+ (recommended for extended-keys support)
• terminal: screen-256color or xterm-256color
• tested on: Linux (Debian/Ubuntu), macOS