Terminal Features

Terminal feature detection and capability management in tmux

Overview

tmux includes a sophisticated terminal feature detection system that automatically identifies and enables advanced terminal capabilities. This allows tmux to provide enhanced functionality when the underlying terminal supports it.

Terminal Features System

Feature Detection

tmux detects terminal features through multiple mechanisms:

• terminfo capabilities: Standard terminal database entries
• Terminal type identification: Recognizing specific terminal emulators
• Device Attributes (DA): Querying the terminal at runtime
• Manual specification: Using the terminal-features option

The feature detection code is implemented in tty-features.c.

Available Terminal Features

tmux supports the following terminal features:

Color Support

256 Colors

# Enable 256 color support
set -g terminal-features "xterm*:256"

# Enable 24-bit RGB color support
set -g terminal-features "xterm*:RGB"

From tty-features.c:116-128, the RGB feature includes:

• setrgbf: Set RGB foreground color (\E[38;2;%p1%d;%p2%d;%p3%dm)
• setrgbb: Set RGB background color (\E[48;2;%p1%d;%p2%d;%p3%dm)
• Support for 256-color palette alongside RGB

Text Attributes

Strikethrough

Enables strikethrough text formatting:

set -g terminal-features "*:strikethrough"

Implemented as escape sequence: \E[9m

Overline

Enables overline text attribute:

set -g terminal-features "*:overline"

Sequence: Smol=\E[53m (from tty-features.c:144-152)

Underscore Styles

Advanced underscore styling with colors:

set -g terminal-features "*:usstyle"

Supports:

• Different underscore types (single, double, curly, dotted, dashed)
• Underscore colors independent of text color
• RGB colors for underscores

From tty-features.c:155-166:

• Smulx: Set underscore style
• Setulc: Set underscore RGB color
• Setulc1: Set underscore palette color

Advanced Features

Title Setting

Window title escape sequences:

set -g terminal-features "*:title"

From tty-features.c:51-60:

• tsl=\E]0; - To status line
• fsl=\a - From status line

Clipboard

OSC 52 clipboard integration:

set -g terminal-features "*:clipboard"

Sequence: Ms=\E]52;%p1%s;%p2%s\a (tty-features.c:86-94)

Mouse Support

Xterm-style mouse tracking:

set -g terminal-features "*:mouse"

Capability: kmous=\E[M (tty-features.c:75-83)

Focus Reporting

Focus in/out events:

set -g terminal-features "*:focus"

From tty-features.c:181-190:

• Enable: Enfcs=\E[?1004h
• Disable: Dsfcs=\E[?1004l

Cursor Customization

Cursor Styles

# Enable cursor style changes
set -g terminal-features "*:cstyle"

From tty-features.c:193-202:

• Ss=\E[%p1%d q - Set cursor style
• Se=\E[2 q - Reset cursor style

Supports various cursor shapes: block, underline, bar, with blinking variants.

Cursor Colors

# Enable cursor color customization
set -g terminal-features "*:ccolour"

From tty-features.c:205-214:

• Cs=\E]12;%p1%s\a - Set cursor color
• Cr=\E]112\a - Reset cursor color

Modern Terminal Features

Extended Keys

Enhanced keyboard protocol support:

set -g terminal-features "*:extkeys"

From tty-features.c:239-248:

• Enable: Eneks=\E[>4;2m
• Disable: Dseks=\E[>4m

Allows distinguishing more key combinations.

Synchronized Updates

Reduces flickering during redraws:

set -g terminal-features "*:sync"

Sequence: Sync=\E[?2026%?%p1%{1}%-%tl%eh%; (tty-features.c:228-236)

Hyperlinks

OSC 8 hyperlink support:

set -g terminal-features "*:hyperlinks"

From tty-features.c:97-109:

• Hls=\E]8;%?%p1%l%tid=%p1%s%;;%p2%s\E\\

Bracketed Paste

Safe paste mode detection:

set -g terminal-features "*:bpaste"

From tty-features.c:169-178:

• Enable: Enbp=\E[?2004h
• Disable: Dsbp=\E[?2004l

Graphics Features

Graphics features require terminal support and compile-time configuration.

Sixel Graphics

set -g terminal-features "*:sixel"

From tty-features.c:350-358, enables sixel image support when compiled with the appropriate libraries.

DECFRA Rectangle Fill

set -g terminal-features "*:rectfill"

From tty-features.c:265-273, enables fast rectangle filling operations:

• Capability: Rect
• Used for optimized screen redraws

DECSLRM Margins

set -g terminal-features "*:margins"

From tty-features.c:251-262, scroll region margins:

• Enable: Enmg=\E[?69h
• Disable: Dsmg=\E[?69l
• Set margins: Cmg=\E[%i%p1%d;%p2%ds

Default Terminal Configurations

tmux includes predefined feature sets for popular terminals (from tty-features.c:468-514):

Modern Terminals Base Set

Most modern terminals support:

256,RGB,bpaste,clipboard,mouse,strikethrough,title

tmux

When running tmux inside tmux:

256,RGB,bpaste,clipboard,mouse,strikethrough,title,
ccolour,cstyle,focus,overline,usstyle,hyperlinks

iTerm2

256,RGB,bpaste,clipboard,mouse,strikethrough,title,
cstyle,extkeys,margins,usstyle,sync,osc7,hyperlinks

XTerm

256,RGB,bpaste,clipboard,mouse,strikethrough,title,
ccolour,cstyle,extkeys,focus

Note: XTerm also supports margins and rectfill, but they can be disabled, so tmux detects them via secondary DA.

mintty

256,RGB,bpaste,clipboard,mouse,strikethrough,title,
ccolour,cstyle,extkeys,margins,overline,usstyle

foot

256,RGB,bpaste,clipboard,mouse,strikethrough,title,
cstyle,extkeys

rxvt-unicode

256,bpaste,ccolour,cstyle,mouse,title,ignorefkeys

Note: rxvt-unicode has quirky function key handling, so tmux uses ignorefkeys to use built-in sequences instead.

Configuration Examples

Override Terminal Type

Force specific features for all terminals:

~/.tmux.conf

# Enable all supported features for any xterm-compatible terminal
set -g terminal-features "xterm*:256:RGB:cstyle:ccolour:clipboard:title:mouse:focus"

# Enable features for tmux terminals specifically
set -ga terminal-features "tmux*:hyperlinks:sync:usstyle:overline"

# Enable strikethrough for all terminals
set -ga terminal-features "*:strikethrough"

Working Directory Tracking

OSC 7 Support

# Enable working directory tracking
set -g terminal-features "*:osc7"

# Capability from tty-features.c:63-72:
# Swd=\E]7; fsl=\a

Disable Specific Features

To disable features that cause problems:

# Don't use terminal's function keys (use tmux built-ins)
set -g terminal-features "rxvt*:ignorefkeys"

From tty-features.c:276-347, this disables kf0 through kf63 terminal capabilities.

Feature Application

1. Feature Detection

   tmux applies features in this order:

   1. Default features based on $TERM environment variable
   2. Device Attributes response (if available)
   3. User-specified terminal-features option
2. Capability Override

   From tty-features.c:434-464, when features are applied:

   for (i = 0; i < nitems(tty_features); i++) {
       if ((term->features & (1 << i)) || (~feat & (1 << i)))
           continue;
       tf = tty_features[i];
       
       log_debug("applying terminal feature: %s", tf->name);
       if (tf->capabilities != NULL) {
           capability = tf->capabilities;
           while (*capability != NULL) {
               log_debug("adding capability: %s", *capability);
               tty_term_apply(term, *capability, 1);
               capability++;
           }
       }
       term->flags |= tf->flags;
   }
   
3. Verification

   Check active features:

   # From outside tmux
   tmux show -g terminal-features
   
   # Check detected features in server info
   tmux info | grep features
   

Best Practices

Let tmux auto-detect features when possible - manual overrides may cause issues

Test feature changes thoroughly - some terminals report capabilities they don’t fully support

Use wildcards carefully - * matches all terminal types

Some features interact with terminal settings. For example:

• extkeys requires terminal support for the extended keyboard protocol
• sync may cause artifacts on slow connections
• margins can conflict with certain terminal scrollback implementations

Debugging Features

Enable tmux logging to see feature detection:

# Start tmux with verbose logging
tmux -vvv new-session

# Check tmux-client-*.log for lines like:
# "adding terminal feature: RGB"
# "adding capability: setrgbf=..."

Related Configuration

• terminal-overrides - Override specific capabilities
• default-terminal - Set TERM value inside tmux
• allow-passthrough - Control escape sequence passthrough