[tmux.app]
tmux 3.8

Docs · Terminals · iTerm2 3.7 · tmux 3.8

iTerm2 tmux integration: native control mode (tmux -CC)

tmux -CC starts tmux in control mode, and iTerm2 on macOS then shows your tmux windows as native iTerm2 tabs and windows and your panes as native splits, with normal scrolling, search and selection. The session still lives in tmux, so it survives iTerm2 quitting or your SSH connection dropping. Use tmux -CC new -A -s main to create or reattach in one command.

Updated Tested on tmux 3.88 min read

On this page
  1. What tmux -CC is: control mode vs normal tmux
  2. Start, attach, detach
  3. iTerm2 settings for tmux integration
  4. Control mode in tmux 3.8 (and what iTerm2 3.7 uses)
  5. Using normal tmux in iTerm2
  6. Start tmux -CC automatically
  7. Troubleshooting iTerm2 + tmux
  8. FAQ

Quick answer

How do I use tmux -CC in iTerm2?

  1. Start or reattach: tmux -CC new -A -s main in iTerm2 (locally or after ssh).
  2. Over SSH in one step: ssh -t server 'tmux -CC new -A -s main'
  3. Work normally: new tabs and splits from iTerm2's Shell → tmux menu and split commands become tmux windows and panes.
  4. Detach: Shell → tmux → Detach, or press Esc in the gateway session. Reattach with tmux -CC attach.
  5. Stuck? Press X in the gateway to force iTerm2 out of tmux mode, then stty sane.

iTerm2 facts come from iTerm2's documentation and George Nachman's "tmux Integration Best Practices" wiki, read 28 October 2026 (iTerm2 3.7.6, built 15 October 2026, macOS 13 or later). The tmux side, including the protocol output below, was run on tmux 3.8; iTerm2 itself was not available on our Linux test machine.

What tmux -CC is: control mode vs normal tmux

Normally tmux draws its windows, panes and status line as text inside one terminal, and you drive it with the prefix key. In control mode, tmux draws nothing. The client prints a text protocol instead: replies to commands between %begin and %end, and notifications such as %output (what a pane printed) and %layout-change. -C starts control mode; -CC also turns off the terminal's echo, and in our test wrapped the whole stream in an escape sequence (\eP1000p … \e\\) that iTerm2 recognizes. iTerm2 reads the protocol and builds native windows from it.

How iTerm2's tmux integration works You run tmux -CC in an iTerm2 session, locally or over SSH. That session becomes the gateway: the tmux client in it speaks control mode, a text protocol of commands and replies such as %begin, %end, %output and %layout-change. iTerm2 reads the protocol and draws each tmux window as a native tab or window and each pane as a native split. The tmux server on the host keeps the session running if iTerm2 quits or the connection drops. iTerm2 (your Mac) native tab: editor split │ split native tab: logs gateway session menu: esc · X · L · C %output commands Host (local or over SSH) tmux -CC client control mode tmux server session "main" window @0: 2 panes window @1: 1 pane keeps running when iTerm2 quits or SSH drops
The session you ran tmux -CC in becomes the gateway. iTerm2 turns protocol messages into tabs and splits; tmux keeps the session.

This is what the protocol looks like. We ran a control-mode client against a tmux 3.8 session with two panes, asked for the windows, and split a pane (long layout strings shortened):

tmux 3.8 control mode (real output)
%begin 1793210667 317 0
%end 1793210667 317 0
%session-changed $0 main
%begin 1793210667 319 1
@0 f09b,120x30,0,0{60x30,0,0,0,59x30,61,0,1}
%end 1793210667 319 1
%window-pane-changed @0 %2
%layout-change @0 {"V":2,"L":{"t":"h","w":120,"h":30,…}} … *
%exit

Run tmux -CC in a terminal that does not speak this protocol (Terminal.app, Ghostty, xterm) and you see text like this or a blank screen. Press Enter on the empty line to leave: in our test an empty line made the control client exit, while Ctrl+c did nothing. The session keeps running.

Normal tmux in iTerm2tmux -CC (control mode)
Windows and panesDrawn as text in one iTerm2 tabNative iTerm2 tabs or windows, native splits
KeysPrefix key (Ctrl+b c, Ctrl+b %)iTerm2 menus and shortcuts; no prefix needed
Scrollback, search, selectiontmux copy modeiTerm2's own (Cmd+F, mouse selection)
Survives disconnectsYesYes, reattach with tmux -CC attach
Window sizesPer windowAll windows share one size, never larger than the smallest attached client
Other terminals, other OSesAnywhereiTerm2 on macOS only

Start, attach, detach

iTerm2
# New session (any name), or attach if "main" exists: what most people want
tmux -CC new -A -s main

# Plain forms from iTerm2's docs
tmux -CC
tmux -CC attach

# On a server: -t gives ssh a terminal, which tmux needs
ssh -t server 'tmux -CC new -A -s main'

When control mode starts, the session you typed in shows a menu, the gateway:

gateway session
** tmux mode started **
Command Menu
----------------------------
esc    Detach cleanly.
  X    Force-quit tmux mode.
  L    Toggle logging.
  C    Run tmux command.

Esc detaches and closes the tmux windows; X forces iTerm2 out of tmux mode if the client died (then run stty sane); L logs the protocol for bug reports; C opens a box for any tmux command, such as new-window. Closing an iTerm2 tab or window in tmux mode kills that tmux window, so detach rather than close when you want to keep things.

iTerm2's best-practices page recommends tmux -CC new -A -s main for one session per machine, Eternal Terminal (et -c "tmux -CC new -A -s main" server) if your IP address changes often, and warns against mosh for tmux integration. It also suggests not typing tmux -CC at a prompt at all, but putting it in a profile's command (for a server: ssh -t server 'tmux -CC new -A -s main'): if the connection dies mid-session, iTerm2 may otherwise send leftover protocol commands to your shell.

iTerm2 settings for tmux integration

Everything lives in Settings → General → tmux:

SettingWhat it does
When attaching, restore windows as…Open tmux windows as native windows or as tabs.
Automatically bury the tmux client session after connectingHides the gateway session (find it later under Session → Buried Sessions).
Use "tmux" profile rather than profile of connecting sessionOff by default since iTerm2 3.3: tmux sessions use the profile you ran tmux -CC in.
Status bar shows tmux status bar contentShows tmux's status line content in iTerm2's status bar.
Pause a pane if it would take more than X seconds to catch upStops a flooded pane from building a huge buffer when a normal tmux client is attached too (tmux 3.2+).
Mirror tmux paste buffer to local clipboardCopies tmux buffers to the macOS clipboard.

With more than ten windows, iTerm2 opens the tmux Dashboard (Shell → tmux → Dashboard) instead of every window; the threshold is set in the dashboard. iTerm2 3.7 added advanced settings to open newly attached tmux windows in the background and to choose where windows created outside iTerm2 appear.

To show tmux window titles as iTerm2 tab titles, the best-practices page suggests:

~/.tmux.conf
set -g set-titles on
set -g set-titles-string '#T'

iTerm2 reads set-titles once when control mode starts, so detach and reattach after changing it.

Control mode in tmux 3.8 (and what iTerm2 3.7 uses)

  • New layout format, opt-in. Layout strings in tmux 3.8 use a JSON format that can describe floating panes. Control-mode clients keep receiving the old format unless they set the new-layouts client flag (refresh-client -f new-layouts or attach -f new-layouts), so existing iTerm2 versions keep working. We set the flag on 3.8 and %layout-change switched to the JSON form shown above.
  • Events and monitors. Hooks and control-mode notifications are now built on one event system. set-hook -B adds "monitor" hooks with the same syntax as refresh-client -B subscriptions, and wait-for -E waits for an event. Details are in tmux scripting.
  • Fixes. Control clients no longer hang on exit when pane output is still queued, and notifications are no longer sent to clients that are exiting.
  • iTerm2 3.7 with newer tmux. iTerm2's docs list OSC 52 clipboard query replies working with tmux 3.6+, and per-pane key reporting and bracketed paste being restored on reattach using tmux 3.5+ formats.

Floating panes (tmux 3.7+) are a tmux concept with no iTerm2 equivalent; iTerm2's documentation does not say how it shows them, so keep floating panes for normal tmux clients.

Using normal tmux in iTerm2

Many people skip control mode and run ordinary tmux in iTerm2, which keeps the prefix keys, copy mode and the same config as on Linux. These settings make it work well:

  • Option as Meta: Settings → Profiles → Keys → General, Left and Right Option key Esc+, for M- bindings in tmux, Neovim and shells.
  • Clipboard: Settings → General → Selection → Applications in terminal may access clipboard, so tmux's OSC 52 copies reach the macOS clipboard.
  • Mouse: keep Settings → Profiles → Terminal → Enable mouse reporting on; tmux 3.8 turns its mouse option on by default, so wheel scrolling and pane clicks work. Hold Option to temporarily bypass mouse reporting and make a normal iTerm2 selection.
~/.tmux.conf (normal tmux in iTerm2)
set -g default-terminal "tmux-256color"
set -as terminal-features ",xterm-256color:RGB"   # iTerm2's default TERM
set -s set-clipboard on
set -g mouse on                                    # default in 3.8

# iTerm2 shell integration and image protocols inside tmux (3.3+)
set -g allow-passthrough on

# Window title in iTerm2's tab and title bar
set -g set-titles on
set -g set-titles-string "#S: #W"

tmux 3.8 also recognizes iTerm2 when a client attaches and turns on its feature set (24-bit color, extended keys, undercurl, synchronized output, hyperlinks and more), so the RGB line is mainly for older tmux. iTerm2's shell integration is off inside tmux unless you export ITERM_ENABLE_SHELL_INTEGRATION_WITH_TMUX=YES before it loads, and needs allow-passthrough on on tmux 3.3 and later.

Badges are iTerm2's text watermark on a session, set with one of its proprietary escape sequences. Inside normal tmux, such sequences only reach iTerm2 through tmux's passthrough, which is why allow-passthrough on is in the config above. In control mode each tmux pane is a separate iTerm2 session, so it gets its own badge.

Start tmux -CC automatically

A profile (recommended by iTerm2). Create a profile per server whose command is ssh -t server 'tmux -CC new -A -s main', or tmux -CC new -A -s main for local use (with Homebrew on Apple Silicon, /opt/homebrew/bin/tmux if the profile cannot find tmux). Opening that profile drops you straight into your tmux tabs.

A trigger. If you must start from an ordinary login, iTerm2 triggers can type the command for you:

  1. Print a marker on the server

    In the server's ~/.bashrc, for interactive SSH logins only: [ -n "$SSH_CONNECTION" ] && [ -z "$TMUX" ] && echo "AUTOMATED_TMUX_READY"
  2. Add a trigger

    iTerm2 → Settings → Profiles → Advanced → Triggers → Edit. Regular expression: ^AUTOMATED_TMUX_READY$.
  3. Make it type the command

    Action Send Text…, parameter tmux -CC new -A -s main\n. Use Send Text, not Run Command: Run Command runs on your Mac, Send Text types into the server's shell.

Troubleshooting iTerm2 + tmux

SymptomFix
Gateway does not respond to EscThe client probably crashed. Press X to force-quit tmux mode, then stty sane. Reattach with tmux -CC attach.
Random commands appear in the shell after a disconnectLeftover protocol traffic. Start tmux -CC from a profile command instead of typing it.
Gray area at the right or bottom of a windowAnother attached client is smaller; tmux windows are never larger than the smallest client. Detach the other client (tmux detach-client -a detaches all others).
A pane says it is pausedIt fell behind (usually with a normal tmux client attached at the same time). Unpause from the notice, or adjust the pause settings above.
Italics show as reverse videoOnly with tmux 3.2 and older defaults (screen TERM). Use set -g default-terminal "tmux-256color".
Copy does not reach the macOS clipboard (normal tmux)Allow clipboard access in iTerm2 and use set -s set-clipboard on; see tmux clipboard.
Cmd+K does not clear tmux history (normal tmux)Cmd+K clears iTerm2's buffer, not the pane's history. Bind a key: bind C-k send-keys -R \; clear-history, then Ctrl+b Ctrl+k.

FAQ

What is tmux -CC in iTerm2?

tmux -CC runs tmux in control mode: instead of drawing its own screen, tmux talks a text protocol that iTerm2 understands, and iTerm2 shows tmux windows as native tabs and panes as native splits. The session still belongs to tmux, so you can detach, close iTerm2, and reattach later with tmux -CC attach.

What is the difference between tmux -C and tmux -CC?

Both start control mode. -C keeps the terminal's echo on, which is handy for testing by hand. -CC turns echo off, which is the form iTerm2 expects.

Does tmux -CC work in Ghostty, Terminal.app or WezTerm?

No; native tmux integration is an iTerm2 feature. Ghostty 1.4 parses parts of the protocol but has not connected it to its interface. In those terminals use normal tmux.

Can I attach to the same session with iTerm2 -CC and a normal tmux client?

Yes. Both are ordinary tmux clients. Window sizes follow the smallest client, and iTerm2 may pause panes that the slower control-mode client cannot keep up with.

How do I hide the gateway window in tmux -CC?

Turn on Settings → General → tmux → Automatically bury the tmux client session after connecting. The gateway moves to Session → Buried Sessions.

Keep learning

Something wrong or out of date on this page? Email hello@tmux.app and we will fix it.