tms

name	tms
description	Connect to a remote tmux session over SSH using iTerm2's native tmux control mode (-CC), creating the session if missing and detaching any stale client. Works on macOS with iTerm2.
author	Greg Z.
author_email	[e-mail]
author_url	https://www.linkedin.com/in/gregzem/

tms — tmux over SSH with iTerm2 integration

A tiny wrapper that attaches to (or creates) a tmux session on a remote host and surfaces it through iTerm2's native tmux integration — so each remote tmux window becomes an iTerm2 tab with real scrollback, native copy/paste, and normal window controls.

Usage

tms connect <host> <session>

Example:

tms connect 10.195.48.28 main

What it does

Runs, on the remote host:

tmux -CC new-session -A -D -s <session>

• -CC — iTerm2 tmux control mode; required for native integration.
• -A — attach to the session if it already exists; otherwise create it.
• -D — detach any other client currently attached, so a new iTerm2 window can take over cleanly.

Requirements

• iTerm2 with tmux integration enabled (default).
• SSH access to <host> (key-based recommended).
• tmux installed on the remote host.

Install

Drop the script on your PATH and make it executable:

install -m 0755 scripts/tms ~/bin/tms

Troubleshooting

• "Cannot Attach — already attached": another client is still holding the session. The -D flag should force-detach it; if the dialog still appears, click Force Detach Other once.
• Scroll doesn't work / windows linger after exit: you're in a plain tmux session, not CC mode. Verify the script contains tmux -CC on the ssh line.
• iTerm2 doesn't open tabs: check Preferences → General → tmux — "Open tmux windows as" should be set to Tabs in the attaching window (or your preference).