Tmux and dim-ed colours in Terminal.app on MacOS

tmux (like GNU screen) works by translating the features of your actual terminal into an (often different) internal terminal. They do this to allow you to connect a session on different terminals at the same time, or at different times.

When that works well, you will see the "same" text no matter where you are connecting from.

Not all terminals support dim. As matter of fact, most do not. The terminal database has 121 occurrences of dim versus 1514 terminal descriptions.

When screen was begun around 1990, its developers chose to ignore that feature and instead supply the most useful. They designed the program to store, for each row/column cell, the video attributes that termcap programs were likely to use. The source-code defines these:

#define ATTR_DI         0       /* Dim mode */
#define ATTR_US         1       /* Underscore mode */
#define ATTR_BD         2       /* Bold mode */
#define ATTR_RV         3       /* Reverse mode */
#define ATTR_SO         4       /* Standout mode */
#define ATTR_BL         5       /* Blinking */

but both screen and tmux use these internal features only if the external terminal supports them, as well as being provided in the internal terminal description.

OSX bundles a copy of ncurses and the terminal database. While you could install MacPorts or homebrew and get a later version, what OSX has is ncurses 5.7.20081102. If you use infocmp to show the terminal descriptions you would see something like this:

$ infocmp screen-256color
#       Reconstructed via infocmp from file: /usr/share/terminfo/73/screen-256color
screen-256color|GNU Screen with 256 colors,
        am, km, mir, msgr, xenl,
        colors#256, cols#80, it#8, lines#24, ncv#3, pairs#32767,
        acsc=++\,\,--..00``aaffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz{{||}}~~,
        bel=^G, blink=\E[5m, bold=\E[1m, cbt=\E[Z, civis=\E[?25l,
        clear=\E[H\E[J, cnorm=\E[34h\E[?25h, cr=^M,
        csr=\E[%i%p1%d;%p2%dr, cub=\E[%p1%dD, cub1=^H,
        cud=\E[%p1%dB, cud1=^J, cuf=\E[%p1%dC, cuf1=\E[C,
        cup=\E[%i%p1%d;%p2%dH, cuu=\E[%p1%dA, cuu1=\EM,
        cvvis=\E[34l, dch=\E[%p1%dP, dch1=\E[P, dl=\E[%p1%dM,
        dl1=\E[M, ed=\E[J, el=\E[K, el1=\E[1K, enacs=\E(B\E)0,
        flash=\Eg, home=\E[H, ht=^I, hts=\EH, ich=\E[%p1%d@,
        il=\E[%p1%dL, il1=\E[L, ind=^J, initc@, is2=\E)0, kbs=^H,
        kcbt=\E[Z, kcub1=\EOD, kcud1=\EOB, kcuf1=\EOC, kcuu1=\EOA,
        kdch1=\E[3~, kend=\E[4~, kf1=\EOP, kf10=\E[21~,
        kf11=\E[23~, kf12=\E[24~, kf2=\EOQ, kf3=\EOR, kf4=\EOS,
        kf5=\E[15~, kf6=\E[17~, kf7=\E[18~, kf8=\E[19~, kf9=\E[20~,
        khome=\E[1~, kich1=\E[2~, kmous=\E[M, knp=\E[6~, kpp=\E[5~,
        nel=\EE, op=\E[39;49m, rc=\E8, rev=\E[7m, ri=\EM, rmacs=^O,
        rmcup=\E[?1049l, rmir=\E[4l, rmkx=\E[?1l\E>, rmso=\E[23m,
        rmul=\E[24m, rs2=\Ec\E[?1000l\E[?25h, sc=\E7,
        setab=\E[%?%p1%{8}%<%t4%p1%d%e%p1%{16}%<%t10%p1%{8}%-%d%e48;5;%p1%d%;m,
        setaf=\E[%?%p1%{8}%<%t3%p1%d%e%p1%{16}%<%t9%p1%{8}%-%d%e38;5;%p1%d%;m,
        sgr=\E[0%?%p6%t;1%;%?%p1%t;3%;%?%p2%t;4%;%?%p3%t;7%;%?%p4%t;5%;m%?%p9%t\016%e\017%;,
        sgr0=\E[m\017, smacs=^N, smcup=\E[?1049h, smir=\E[4h,
        smkx=\E[?1h\E=, smso=\E[3m, smul=\E[4m, tbc=\E[3g,

There is no dim there. In ncurses, this was added in April 2015:

# 2015-04-22
#       + add 'dim' capability to screen entry (report by Leonardo B Schenkel)
#       + add several key definitions to nsterm-bce to match preconfigured
#         keys, e.g., with OSX 10.9 and 10.10 (report by Leonardo B Schenkel)

Likewise, you would not see dim in xterm-256color. That was added in June 2014:

# 2014-06-14
#       + modify sgr for screen.xterm-new to support dim capability -TD
#       + add dim capability to nsterm+7 -TD
#       + cancel dim capability for iterm -TD
#       + add dim, invis capabilities to vte-2012 -TD
#       + add sitm/ritm to konsole-base and mlterm3 -TD

The manner in which dim is used in the external Terminal.app is not indicated, but likely hardcoded (not using the terminal description). But screen and tmux do not know how the escape sequences come in, but know that dim is not mentioned in the terminal description, hence not supported.

You can update your terminfo database to add the dim feature to these terminal descriptions, using the infocmp and tic utilities:

• use infocmp to get the existing terminal descriptions for xterm-256color and screen-256color. This shows just the first; you would of course repeat the process for the second description:

  infocmp -1x xterm-256color > foo

• edit the text file created by infocmp, adding this line

  dim=\E[2m,
  

  and replacing the line with sgr= with this line:

  sgr=%?%p9%t\E(0%e\E(B%;\E[0%?%p6%t;1%;%?%p5%t;2%;%?%p2%t;4%;%?%p1%p3%|%t;7%;%?%p4%t;5%;%?%p7%t;8%;m,
  

• use tic to replace the terminal description:

  sudo tic -x foo

Note: The point of the question was asking why this happens; Nicholas Marriott provided the information for how to work around the problem.