Fixing iTerm2 tmux Control Mode (-CC) Hanging

Problem

When attempting to use iTerm2's tmux Control Mode integration with a remote server, the connection hangs with this error:

Slow tmux Response

It's taking a long time for tmux to respond. If this is an old or funky system it
might expect newline rather than carriage return to end commands. You can adjust
the line terminator used by tmux integration in Settings.

Environment

• OS: macOS
• tmux version: 3.3a
• iTerm2: Latest version
• Connection: SSH to remote server
• Command: ssh remote-host -t tmux -CC new-session -A -s session

Root Cause

The issue is caused by tmux plugins (specifically tmux-claude-status and TPM - Tmux Plugin Manager) interfering with iTerm2's Control Mode protocol communication.

Control Mode uses special control sequences that plugins' daemon monitor scripts can disrupt.

What DIDN'T Work

These commonly suggested fixes did NOT resolve the issue:

1. ❌ Enabling "Send \n rather than \r to terminate commands" in iTerm2 → Preferences → Profiles → Terminal
2. ❌ Enabling "Automatically bury the tmux client session" in iTerm2 → Preferences → General → tmux
3. ❌ Changing escape-time 0 to escape-time 10 in ~/.tmux.conf
4. ❌ Restarting tmux server
5. ❌ Killing and recreating sessions

The Solution

Step 1: Create Minimal tmux Configuration

Backup your current config:

ssh remote-host 'cp ~/.tmux.conf ~/.tmux.conf.backup'

Create a minimal config WITHOUT plugins:

ssh remote-host 'cat > ~/.tmux.conf << '\''EOF'\''
set -g history-limit 100000
set -g mouse on
set -s escape-time 10
set -g status-right-length 100
EOF'

Step 2: Kill tmux Server

ssh remote-host 'tmux kill-server'

This forces tmux to reload the configuration on next start.

Step 3: Test Control Mode

ssh remote-host -t tmux -CC new-session -A -s mysession

It should now connect immediately without hanging!

Understanding the Fix

The problematic configuration typically looks like:

# ❌ This causes the hang:
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'samleeney/tmux-claude-status'
run '~/.tmux/plugins/tpm/tpm'

# These daemon scripts interfere with Control Mode:
if-shell "test -f ~/.tmux/plugins/tmux-claude-status/tmux-claude-status.tmux" \
    "run-shell ~/.tmux/plugins/tmux-claude-status/tmux-claude-status.tmux"

When these run, background daemon processes interfere with iTerm2's Control Mode protocol.

Restoring Your Plugins

If you want your plugins back, you have options:

Option 1: Use Regular tmux (Without -CC)

ssh remote-host -t tmux attach -t mysession

Plugins work fine with regular tmux mode.

Option 2: Conditional Configuration

Create two configs:

• ~/.tmux.conf - Minimal (for Control Mode)
• ~/.tmux-full.conf - With plugins (for regular mode)

Use regular tmux when you need plugins:

tmux -f ~/.tmux-full.conf attach

Option 3: Test Plugins Individually

If you want to identify which specific plugin causes issues:

1. Start with minimal config
2. Add TPM only (without tmux-claude-status)
3. Test if Control Mode works
4. Add other plugins one at a time

Debugging Tips

Check Running tmux Processes

ssh remote-host 'ps aux | grep tmux'

Look for daemon monitor scripts or background processes.

Verify Configuration

ssh remote-host 'cat ~/.tmux.conf'

Check tmux Server Status

ssh remote-host 'tmux list-sessions'

Additional iTerm2 Settings

While these didn't fix the plugin issue, they're recommended for Control Mode:

Preferences → General → tmux:

• ✅ Check "Automatically bury the tmux client session after connecting"
• Choose "When attaching, restore windows as": Native windows

Preferences → Profiles → Terminal:

• ✅ Check "Send \n rather than \r to terminate commands" (for compatibility with some systems)

Related Resources

• iTerm2 tmux Integration Documentation
• tmux Control Mode Wiki
• iTerm2 tmux Best Practices
• GitHub Issue

Summary

Problem: tmux plugins cause iTerm2 Control Mode to hang
Solution: Use minimal tmux config without plugins
Alternative: Use regular tmux mode (without -CC) if you need plugins

The key insight is that iTerm2's Control Mode requires a clean communication channel with tmux, and background daemon processes from plugins interfere with this protocol.