Tmux with Native Scrollback on macOS

Tmux is a powerful terminal multiplexer that lets you run multiple terminal sessions within a single window. However, when using tmux with macOS Terminal.app, you’ll encounter two common frustrations: colors don’t display properly, and you can’t use your terminal’s native scroll functionality. Instead, tmux captures scrolling and requires you to enter “copy mode” just to view previous output.

The Problem

By default, tmux has two behaviors that don’t work well with Terminal.app:

• Color Issues: Terminal colors appear washed out or incorrect because tmux doesn’t properly communicate terminal capabilities
• Scrollback Captured: When you try to scroll up with your trackpad or mouse wheel, nothing happens—tmux captures the alternate screen and requires Ctrl+b [ to enter copy mode for viewing history

For users accustomed to Terminal.app’s native scrolling, this creates unnecessary friction in the workflow.

The Solution

You can configure tmux to respect Terminal.app’s native behavior while maintaining all of tmux’s session management features.

Configuration

Enable Colors and Native Scrollback

Create or edit ~/.tmux.conf and add:

# Show colors
set -g default-terminal "xterm-color"

# Allow native scroll back in terminal.app
set -ga terminal-overrides 'xterm*:smcup@:rmcup@'

Display Hostname in Tmux Tabs

Add this to your ~/.bashrc or ~/.bash_profile:

# Tmux/Screen tab title
case "$TERM" in
screen)
  PROMPT_COMMAND="printf '\\033k$(hostname -s)\\033\\';"${PROMPT_COMMAND}
  ;;
esac

How It Works

Color Configuration

set -g default-terminal "xterm-color"

This tells tmux to identify itself as an xterm-color terminal, which ensures proper color codes are sent to Terminal.app. Without this setting, tmux may default to a basic terminal type that doesn’t support the full color palette.

Native Scrollback

set -ga terminal-overrides 'xterm*:smcup@:rmcup@'

This is the key setting that enables native scrollback. Let’s break it down:

• set -ga terminal-overrides: Appends to the terminal overrides (the -a flag means append, not replace)
• 'xterm*:smcup@:rmcup@': Targets xterm-like terminals and disables two capabilities:
  – smcup@: Disables “save cursor position” alternate screen
  – rmcup@: Disables “restore cursor position” alternate screen

By disabling the alternate screen capabilities, tmux no longer captures the scrollback buffer. This allows Terminal.app to maintain its own scrollback history, which you can access with normal scrolling.

Hostname in Tab Titles

case "$TERM" in
screen)
  PROMPT_COMMAND="printf '\\033k$(hostname -s)\\033\\';"${PROMPT_COMMAND}
  ;;
esac

This configuration:

• Checks if you’re running in tmux or screen (both use TERM=screen)
• Uses PROMPT_COMMAND to run before each prompt
• Sends escape sequences (\033k and \033\\) that set the tab/window title
• Displays the short hostname using $(hostname -s)

This is particularly helpful when you’re connected to multiple servers—each tab clearly shows which machine you’re working on.

Installation

• Create or edit your tmux configuration:
  bash nano ~/.tmux.conf
  
• Add the color and scrollback settings shown above
  
• Edit your bash profile:
  bash nano ~/.bashrc
  (Or ~/.bash_profile on macOS)
  
• Add the hostname tab title configuration
  
• Reload tmux configuration:
  – If tmux is running: Press Ctrl+b then type :source-file ~/.tmux.conf
  – Or restart tmux completely
  
• Reload bash configuration:
  bash source ~/.bashrc

Testing

Start a new tmux session:

tmux new -s test

Test the configuration:

• Colors: Run ls --color=auto and verify colors display correctly
• Scrollback: Run commands to generate output, then scroll up with your trackpad—you should see previous output
• Hostname: Check your tmux tab title—it should show your machine’s short hostname

Benefits

Native Scrolling: Use your trackpad or mouse wheel to scroll through history naturally, just like in a normal terminal session.

Proper Colors: Syntax highlighting and color-coded output display correctly in Terminal.app.

Easy Navigation: When working with multiple tmux sessions across different servers, the hostname in each tab title makes it easy to identify which machine you’re on.

No Copy Mode: You don’t need to remember Ctrl+b [ just to view your command history.

Trade-offs

Copy Mode Still Available: While native scrollback works for viewing history, tmux’s copy mode (Ctrl+b [) is still useful for advanced operations like searching history or copying text using vi-style keybindings.

Terminal.app Specific: This configuration is optimized for Terminal.app. If you use iTerm2, you may want different settings.

Scrollback Limits: You’re now limited by Terminal.app’s scrollback buffer settings rather than tmux’s. Adjust Terminal.app preferences if you need more history.

Notes

Why -ga instead of -g: The -ga flag appends to existing terminal overrides rather than replacing them. This is important if you have other terminal override settings or if tmux sets defaults you want to preserve.

Alternative Terminals: If you use iTerm2, you may not need the scrollback override as iTerm2 has better tmux integration built in. Test both configurations to see which works better for your workflow.

Screen Users: The hostname configuration works for both tmux and GNU Screen since both set TERM=screen.

View the original configurations on Gist: .tmux.conf and .bashrc.