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.
On this page
Quick answer
How do I use tmux -CC in iTerm2?
- Start or reattach:
tmux -CC new -A -s mainin iTerm2 (locally or afterssh). - Over SSH in one step:
ssh -t server 'tmux -CC new -A -s main' - Work normally: new tabs and splits from iTerm2's Shell → tmux menu and split commands become tmux windows and panes.
- Detach: Shell → tmux → Detach, or press Esc in the gateway session. Reattach with
tmux -CC attach. - 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.
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):
%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,…}} … *
%exitRun 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 iTerm2 | tmux -CC (control mode) | |
|---|---|---|
| Windows and panes | Drawn as text in one iTerm2 tab | Native iTerm2 tabs or windows, native splits |
| Keys | Prefix key (Ctrl+b c, Ctrl+b %) | iTerm2 menus and shortcuts; no prefix needed |
| Scrollback, search, selection | tmux copy mode | iTerm2's own (Cmd+F, mouse selection) |
| Survives disconnects | Yes | Yes, reattach with tmux -CC attach |
| Window sizes | Per window | All windows share one size, never larger than the smallest attached client |
| Other terminals, other OSes | Anywhere | iTerm2 on macOS only |
Start, attach, detach
# 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:
** 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:
| Setting | What it does |
|---|---|
| When attaching, restore windows as… | Open tmux windows as native windows or as tabs. |
| Automatically bury the tmux client session after connecting | Hides the gateway session (find it later under Session → Buried Sessions). |
| Use "tmux" profile rather than profile of connecting session | Off by default since iTerm2 3.3: tmux sessions use the profile you ran tmux -CC in. |
| Status bar shows tmux status bar content | Shows tmux's status line content in iTerm2's status bar. |
| Pause a pane if it would take more than X seconds to catch up | Stops 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 clipboard | Copies 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:
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-layoutsclient flag (refresh-client -f new-layoutsorattach -f new-layouts), so existing iTerm2 versions keep working. We set the flag on 3.8 and%layout-changeswitched to the JSON form shown above. - Events and monitors. Hooks and control-mode notifications are now built on one event system.
set-hook -Badds "monitor" hooks with the same syntax asrefresh-client -Bsubscriptions, andwait-for -Ewaits 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
mouseoption on by default, so wheel scrolling and pane clicks work. Hold Option to temporarily bypass mouse reporting and make a normal iTerm2 selection.
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:
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"Add a trigger
iTerm2 → Settings → Profiles → Advanced → Triggers → Edit. Regular expression:^AUTOMATED_TMUX_READY$.Make it type the command
Action Send Text…, parametertmux -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
| Symptom | Fix |
|---|---|
| Gateway does not respond to Esc | The 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 disconnect | Leftover protocol traffic. Start tmux -CC from a profile command instead of typing it. |
| Gray area at the right or bottom of a window | Another 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 paused | It 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 video | Only 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.