How do I start iTerm2 tmux Control Mode?

Run 'tmux -CC' to create a new session in Control Mode, or 'tmux -CC attach' to attach to an existing session. iTerm2 will automatically open native macOS tabs for each tmux window.

Documentation · iTerm2 · macOS Integration

iTerm2 + tmux
Integration Guide

Q: What is iTerm2 tmux Control Mode (tmux -CC)?

Control Mode allows iTerm2 to communicate with a remote or local tmux server as a protocol client. Instead of rendering ASCII terminal panes, iTerm2 creates native macOS GUI tabs and split windows driven by the underlying tmux daemon.

Q: How do I automatically hide the control window when attaching with tmux -CC?

In iTerm2, navigate to Preferences > General > Services > tmux integration and check 'Hide the control client window automatically' to keep your terminal workspace clean.

Discover how to use iTerm2 with tmux on macOS — exploring native Control Mode (tmux -CC) for GUI tab rendering versus standard terminal multiplexing.

TL;DR Overview

iTerm2 + tmux Integration Summary:

iTerm2 Control Mode (tmux -CC) renders tmux windows as native macOS GUI tabs and splits
Preserves server-side daemon persistence while allowing native macOS Cocoa mouse selection and key shortcuts
Standard CLI tmux can also be run inside iTerm2 with default-terminal "tmux-256color"
Configure Preferences > General > Services to auto-hide control windows and sync clipboards

Control Mode (tmux -CC) vs Standard tmux

Compare native macOS GUI window rendering with terminal-based ANSI multiplexing.

Feature	Standard CLI tmux	iTerm2 Control Mode (`tmux -CC`)
UI Rendering	In-terminal ASCII character grid	Native macOS GUI windows, tabs, and splits
Mouse Selection	tmux copy mode buffers	Native macOS Cocoa text selection
Keybindings	`Prefix + c`, `Prefix + %`	Native macOS shortcuts (`Cmd+T`, `Cmd+D`)
Session Persistence	✅ Full server persistence	✅ Full server persistence
Cross-Platform	✅ Linux, macOS, WSL	❌ macOS only (iTerm2 dependency)

bash

# Start a new iTerm2 Control Mode session

$ tmux -CC

# Attach to an existing session in Control Mode

$ tmux -CC attach -t dev-session

Standard iTerm2 Configuration (~/.tmux.conf)

Prevent Option key conflicts and configure title bar sync for standard CLI multiplexing.

⚙ Preferences Settings

Option Key: Set Left/Right Option Key to Esc+ (Meta key forwarding).
Mouse Reporting: Enable mouse reporting under Terminal preferences.
Clipboard Access: Allow terminal applications to access system clipboard.
Auto-Hide Controller: Check Preferences > General > Services > Hide control window.

📄 Recommended Settings

Configure 24-bit RGB colors, mouse support, system clipboard integration, and iTerm2 window title synchronization in your config file.

~/.tmux.conf

set -g default-terminal "tmux-256color"

set -ga terminal-overrides ",xterm-256color:Tc"

set -g mouse on

set -s set-clipboard on

# Sync tmux title to iTerm2 window bar

set -g set-titles on

set -g set-titles-string "#S: #W (#I/#P)"

Automated SSH Triggers & Auto-Attach

Configure iTerm2 to automatically initiate Control Mode sessions upon SSH login.

🚀 iTerm2 Trigger Setup Steps

Open iTerm2 Preferences > Profiles > Advanced > Triggers and click Edit.
Add a Trigger with Regular Expression: ^AUTOMATED_TMUX_READY
Set Action to: Run Command... with value: tmux -CC attach -t dev || tmux -CC new -s dev
In your remote ~/.bashrc, print echo "AUTOMATED_TMUX_READY" on login.

Troubleshooting iTerm2 + tmux

Solutions for common Control Mode, clipboard, and scrollback clearing issues.

1. Control Mode Frozen Window

When disconnecting from a tmux -CC session, press Esc inside the controller terminal window to regain command prompt focus.

2. Clipboard Synchronization

Ensure set -s set-clipboard on is enabled in ~/.tmux.conf and iTerm2 clipboard permissions are allowed.

3. Cmd+K History Clearing

Native Cmd+K clears iTerm2's window buffer. Add bind -n C-k send-keys -R \; clear-history to your ~/.tmux.conf to clear scrollback on Ctrl+k.

Frequently Asked Questions

Common answers regarding iTerm2 Control Mode and macOS multiplexing.

What is iTerm2 tmux Control Mode (tmux -CC)?

Control Mode translates tmux sessions into native macOS Cocoa GUI windows, tabs, and split panes while maintaining session persistence on the underlying tmux daemon.

Can I use macOS native shortcuts (Cmd+T, Cmd+D) with tmux -CC?

Yes! In Control Mode, iTerm2 handles window management directly, allowing you to use Cmd+T (new tab), Cmd+D (split vertically), and Cmd+Shift+D (split horizontally).

How do I hide the extra controller terminal window in tmux -CC?

Go to iTerm2 Preferences > General > Services > tmux integration and check "Hide the control client window automatically".

Explore Related Documentation

Deepen your tmux integration knowledge with these related guides.