Tmux

How to configure allow-passthrough in tmux?

Quick Answer

To enable escape sequence passthrough in tmux (available in tmux 3.2+), add set -g allow-passthrough on to your ~/.tmux.conf file. This allows applications running inside tmux to receive and process certain terminal escape sequences directly, improving compatibility with terminal features like OSC 52 clipboard integration, hyperlinks, and images. For older tmux versions, use the terminal-overrides option for specific sequences.

# For tmux 3.2 and newer
set -g allow-passthrough on

# For older versions
set -g terminal-overrides "xterm*:XT:Ms=\\E]52;%p1%s;%p2%s\\007"

Detailed Explanation

Terminal escape sequences are special character sequences that control terminal behavior, such as changing colors, moving the cursor, or enabling special features. By default, tmux intercepts many of these sequences and processes them itself, which can cause compatibility issues with applications that rely on direct communication with the terminal.

Understanding allow-passthrough

The allow-passthrough option was introduced in tmux 3.2 to solve compatibility issues by allowing certain escape sequences to pass through tmux directly to the terminal emulator. This improves support for:

Clipboard operations (OSC 52)
Hyperlinks in terminal
Terminal-based images (iTerm2, Kitty)
Advanced styling and formatting
Custom application-specific terminal features

Configuration for tmux 3.2 and newer

To enable passthrough in modern tmux versions, add this line to your ~/.tmux.conf:

# Enable passthrough of escape sequences
set -g allow-passthrough on

You can also configure which specific escape sequence types are allowed through by passing arguments:

# Allow only specific escape sequences (example)
set -g allow-passthrough "on,\e]52;,\e]1337;File="

Clipboard Integration Example

One common use case for passthrough is enabling clipboard operations using OSC 52 sequences. This allows copying text from remote tmux sessions to your local clipboard:

# In ~/.tmux.conf
set -g allow-passthrough on
set -g set-clipboard on  # Enable OSC 52 clipboard

# For older tmux versions
set -g terminal-overrides "xterm*:XT:Ms=\\E]52;%p1%s;%p2%s\\007"

Terminal Image Support

Another useful application is enabling image display in terminal applications:

# For iTerm2 image protocol
set -g allow-passthrough on

# You might need additional configuration
set -ga terminal-features ",xterm-256color:RGB"
set -ga terminal-overrides ",xterm-256color:Tc"

Testing passthrough

To test if your passthrough configuration is working, you can use a simple script:

#!/bin/bash
# Test OSC 52 clipboard support
echo -e "\033]52;c;$(echo "test clipboard" | base64)\a"

# For hyperlink support
echo -e "\e]8;;https://tmux.github.io\e\\This is a hyperlink\e]8;;\e\\"

Pro Tip

You can selectively enable passthrough for specific applications. For example, to enable it only for Neovim:

# Create a command to toggle passthrough
bind-key P if-shell "tmux show-option -g allow-passthrough | grep -q on" \
    "set -g allow-passthrough off; display 'Passthrough: OFF'" \
    "set -g allow-passthrough on; display 'Passthrough: ON'"

This creates a Ctrl+b P shortcut to toggle passthrough on/off.

Troubleshooting

If passthrough isn't working:

Check your tmux version with tmux -V (3.2+ needed for allow-passthrough)
Ensure your terminal emulator supports the features you're trying to use
For older tmux versions, use the more specific terminal-overrides approach
Try prefixing your configuration with if-shell "tmux -V | grep -q 'tmux 3.[2-9]'" "set -g allow-passthrough on" to conditionally apply it
Check if any other tmux options like set-clipboard might be interfering

←Back to FAQ Index